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

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

סקירה כללית של ערכת ה-SDK המקומית

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

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

הפונקציות של הבקשה וההפעלה מחזירות את הערך REVIEW_NO_ERROR אם הפונקציה מצליחה.

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

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

   • מתקינים את Android Studio בגרסה 4.0 ואילך. משתמשים בממשק המשתמש של SDK Manager כדי להתקין את גרסה 10.0 של Android SDK Platform (רמת 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.16.0.zip	54.8 MiB	008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

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.6.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.6.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

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

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

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

Include 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();

השלבים הבאים

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