שילוב של ביקורות בתוך האפליקציה (מודעות מותאמות)

במדריך הזה מוסבר איך לשלב באפליקציה בקשות לביקורת באפליקציה באמצעות קוד מקורי (C או C++‎). יש מדריכי שילוב נפרדים אם אתם משתמשים ב-Kotlin או ב-Java, ב-Unity או ב-Unreal Engine.

סקירה כללית של Native SDK

‫Play Core Native SDK הוא חלק ממשפחת ספריות Google Play Core. ערכת Play Core Native SDK כוללת קובץ כותרת C‏, review.h, שעוטף את ReviewManager מהספריות של Java Play In-App Review. קובץ הכותרת הזה מאפשר לאפליקציה שלכם להפעיל את ה-API ישירות מהקוד המקורי. במסמכי המודול המקורי של Play Review יש סקירה כללית של הפונקציות הציבוריות שזמינות.

הפונקציה ReviewManager_requestReviewFlow מתחילה בקשה לאיסוף המידע שנדרש להפעלת תהליך הבדיקה בתוך האפליקציה בהמשך. אפשר לעקוב אחרי התוצאה של הבקשה באמצעות ReviewManager_getReviewStatus. מידע נוסף על כל הסטטוסים ש-ReviewManager_getReviewStatus יכול להחזיר מופיע במאמר ReviewErrorCode.

הפונקציות request ו-launch מחזירות REVIEW_NO_ERROR אם הפונקציה מצליחה.

הגדרת סביבת הפיתוח

1. בצע אחת מהפעולות הבאות:

   • מתקינים את Android Studio בגרסה 4.0 ואילך. משתמשים בממשק המשתמש של SDK Manager כדי להתקין את Android SDK Platform בגרסה 10.0 (רמת API‏ 29).
   • מתקינים את כלי שורת הפקודה של Android SDK ומשתמשים ב-sdkmanager כדי להתקין את Android SDK Platform בגרסה 10.0 (רמת API‏ 29).

2. כדי להכין את Android Studio לפיתוח מקורי, משתמשים בSDK Manager כדי להתקין את הגרסה העדכנית של CMake ושל Android Native Development Kit‏ (NDK). מידע נוסף על יצירה או ייבוא של פרויקטים מקוריים זמין במאמר תחילת העבודה עם NDK.

3. מורידים את קובץ ה-ZIP ומחלצים אותו לצד הפרויקט.

   קישור להורדה	גודל	סיכום ביקורת (checksum)‏ SHA-256
   play-core-native-sdk-1.15.3.zip	‫37.8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

4. מעדכנים את הקובץ build.gradle של האפליקציה כמו שמוצג בהמשך:

   מגניב

       // App build.gradle
   
       plugins {
         id 'com.android.application'
       }
   
       // Define a path to the extracted Play Core SDK files.
       // If using a relative path, wrap it with file() since CMake requires absolute paths.
       def playcoreDir = file('../path/to/playcore-native-sdk')
   
       android {
           defaultConfig {
               ...
               externalNativeBuild {
                   cmake {
                       // Define the PLAYCORE_LOCATION directive.
                       arguments "-DANDROID_STL=c++_static",
                                 "-DPLAYCORE_LOCATION=$playcoreDir"
                   }
               }
               ndk {
                   // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
                   abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
               }
           }
           buildTypes {
               release {
                   // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
                   proguardFile '$playcoreDir/proguard/common.pgcfg'
                   proguardFile '$playcoreDir/proguard/gms_task.pgcfg'
                   proguardFile '$playcoreDir/proguard/per-feature-proguard-files'
                   ...
               }
               debug {
                   ...
               }
           }
           externalNativeBuild {
               cmake {
                   path 'src/main/CMakeLists.txt'
               }
           }
       }
   
       dependencies {
           // Import these feature-specific AARs for each Google Play Core library.
           implementation 'com.google.android.play:app-update:2.1.0'
           implementation 'com.google.android.play:asset-delivery:2.3.0'
           implementation 'com.google.android.play:integrity:1.4.0'
           implementation 'com.google.android.play:review:2.0.2'
   
           // Import these common dependencies.
           implementation 'com.google.android.gms:play-services-tasks:18.0.2'
           implementation files("$playcoreDir/playcore-native-metadata.jar")
           ...
       }
       

   Kotlin

   // App build.gradle
   
   plugins {
       id("com.android.application")
   }
   
   // Define a path to the extracted Play Core SDK files.
   // If using a relative path, wrap it with file() since CMake requires absolute paths.
   val playcoreDir = file("../path/to/playcore-native-sdk")
   
   android {
       defaultConfig {
           ...
           externalNativeBuild {
               cmake {
                   // Define the PLAYCORE_LOCATION directive.
                   arguments += listOf("-DANDROID_STL=c++_static", "-DPLAYCORE_LOCATION=$playcoreDir")
               }
           }
           ndk {
               // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
               abiFilters.clear()
               abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")
           }
       }
       buildTypes {
           release {
               // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
               proguardFile("$playcoreDir/proguard/common.pgcfg")
               proguardFile("$playcoreDir/proguard/gms_task.pgcfg")
               proguardFile("$playcoreDir/proguard/per-feature-proguard-files")
               ...
           }
           debug {
               ...
           }
       }
       externalNativeBuild {
           cmake {
               path = "src/main/CMakeLists.txt"
           }
       }
   }
   
   dependencies {
       // Import these feature-specific AARs for each Google Play Core library.
       implementation("com.google.android.play:app-update:2.1.0")
       implementation("com.google.android.play:asset-delivery:2.3.0")
       implementation("com.google.android.play:integrity:1.4.0")
       implementation("com.google.android.play:review:2.0.2")
   
       // Import these common dependencies.
       implementation("com.google.android.gms:play-services-tasks:18.0.2")
       implementation(files("$playcoreDir/playcore-native-metadata.jar"))
       ...
   }

5. מעדכנים את הקבצים CMakeLists.txt של האפליקציה באופן הבא:

   cmake_minimum_required(VERSION 3.6)
   
   ...
   
   # Add a static library called “playcore” built with the c++_static STL.
   include(${PLAYCORE_LOCATION}/playcore.cmake)
   add_playcore_static_library()
   
   // In this example “main” is your native code library, i.e. libmain.so.
   add_library(main SHARED
           ...)
   
   target_include_directories(main PRIVATE
           ${PLAYCORE_LOCATION}/include
           ...)
   
   target_link_libraries(main
           android
           playcore
           ...)
   

איסוף נתונים

יכול להיות ש-Play Core Native SDK יאסוף נתונים שקשורים לגרסה כדי לאפשר ל-Google לשפר את המוצר, כולל:

• שם החבילה של האפליקציה
• גרסת החבילה של האפליקציה
• הגרסה של Play Core Native SDK

הנתונים האלה ייאספו כשתעלו את חבילת האפליקציה ל-Play Console. כדי לבטל את ההסכמה לתהליך איסוף הנתונים הזה, צריך להסיר את השורה $playcoreDir/playcore-native-metadata.jar import בקובץ build.gradle.

חשוב לציין שהאיסוף הזה של נתונים שקשורים לשימוש שלכם ב-Play Core Native SDK והשימוש של Google בנתונים שנאספים הם נפרדים ועצמאיים מאיסוף יחסי התלות של הספריות שמוצהרים ב-Gradle על ידי Google כשאתם מעלים את חבילת האפליקציה שלכם ל-Play Console.

אחרי שמשלבים את Play Core Native SDK בפרויקט, צריך לכלול את השורה הבאה בקבצים שמכילים קריאות ל-API:

כוללים את review.h

אחרי שמשלבים את Play Core Native SDK בפרויקט, מוסיפים את השורה הבאה לקבצים שיכילו קריאות ל-API:

#include "play/review.h"

הפעלת Review API

בכל פעם שרוצים להשתמש ב-API, צריך קודם לאתחל אותו באמצעות קריאה לפונקציה ReviewManager_init, כמו בדוגמה הבאה שנוצרה באמצעות android_native_app_glue.h:

void android_main(android_app* app) {
  app->onInputEvent = HandleInputEvent;

  ReviewErrorCode error_code = ReviewManager_init(app->activity->vm, app->activity->clazz);
  if (error_code == REVIEW_NO_ERROR) {
    // You can use the API.
  }
}

שליחת בקשה להפעלת תהליך בדיקת האפליקציה

כדי לקבוע נקודות טובות בתהליך השימוש של המשתמש באפליקציה שבהן כדאי להציג בקשה לכתיבת ביקורת (לדוגמה, אחרי שהמשתמש סוגר את מסך הסיכום בסוף שלב במשחק), מומלץ לעיין בהנחיות בנושא מתי כדאי לבקש ביקורות באפליקציה. כשהאפליקציה מתקרבת לאחת מהנקודות האלה, צריך להתקשר אל ReviewManager_requestReviewFlow כדי לבקש באופן אסינכרוני את המידע שהאפליקציה צריכה כדי להפעיל תהליך של שליחת ביקורת בתוך האפליקציה. כדי לעקוב אחרי ההתקדמות של הפעולה ReviewManager_requestReviewFlow, קוראים לפונקציה ReviewManager_getReviewStatus, למשל פעם בכל פריים. יכול להיות שייקח כמה שניות עד שהתהליך יתחיל, לכן כדאי להתחיל אותו לפני שהאפליקציה מגיעה לנקודה שבה רוצים להציג את תהליך שליחת הביקורת באפליקציה.

ReviewErrorCode error_code = ReviewManager_requestReviewFlow();
if (error_code == REVIEW_NO_ERROR) {
    // The request has successfully started, check the status using
    // ReviewManager_getReviewStatus.
} else {
    // Error such as REVIEW_PLAY_STORE_NOT_FOUND indicating that the in-app
    // review isn't currently possible.
}

טיפול בסטטוסים והפעלת תהליך שליחת הביקורת באפליקציה

אחרי שהבקשה מתחילה או שתהליך הבדיקה בתוך האפליקציה מופעל, אפשר לבדוק את הסטטוס באמצעות ReviewManager_getReviewStatus. כך תוכלו להגדיר את הלוגיקה בהתאם לסטטוס של ה-API. אחת הדרכים לעשות את זה היא להגדיר את הסטטוס כמשתנה גלובלי ולבדוק אם הסטטוס הוא REVIEW_REQUEST_FLOW_COMPLETED כשהמשתמש מבצע פעולה מסוימת (לדוגמה, מקיש על הלחצן 'השלב הבא' במשחק), כמו בדוגמה הבאה:

ReviewStatus status;
ReviewErrorCode error_code = ReviewManager_getReviewStatus(&status);
if (error_code != REVIEW_NO_ERROR) {
    // There was an error with the most recent operation.
    return;
}

switch (status) {
    case REVIEW_REQUEST_FLOW_PENDING:
        // Request is ongoing. The flow can't be launched yet.
        break;
    case REVIEW_REQUEST_FLOW_COMPLETED:
        // Request completed. The flow can be launched now.
        break;
    case REVIEW_LAUNCH_FLOW_PENDING:
        // The review flow is ongoing, meaning the dialog might be displayed.
        break;
    case REVIEW_LAUNCH_FLOW_COMPLETED:
        // The review flow has finished. Continue with your app flow (for
        // example, move to the next screen).
        break;
    default:
        // Unknown status.
        break;
}

כשהסטטוס הוא REVIEW_REQUEST_FLOW_COMPLETED והאפליקציה מוכנה, מפעילים את תהליך הבדיקה בתוך האפליקציה:

// This call uses android_native_app_glue.h.
ReviewErrorCode error_code = ReviewManager_launchReviewFlow(app->activity->clazz);
if (error_code != REVIEW_NO_ERROR) {
    // There was an error while launching the flow.
    return;
}

אחרי שמפעילים את תהליך הבקשה לביקורת באפליקציה, ממשיכים לבדוק את הסטטוס עד להשלמת התהליך וממשיכים בתהליך השימוש באפליקציה. דרך נפוצה לטפל בזה היא באמצעות התבנית Game Loop.

משאבים בחינם

חשוב לזכור לשחרר משאבים על ידי קריאה לפונקציה ReviewManager_destroy אחרי שהאפליקציה סיימה להשתמש ב-API (לדוגמה, אחרי שהמשתמש השלים את תהליך שליחת הביקורת באפליקציה).

void ReviewManager_destroy();

השלבים הבאים

בודקים את תהליך שליחת הביקורת באפליקציה כדי לוודא שההטמעה פועלת בצורה תקינה.