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

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

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

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

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

גם פונקציית הבקשה וגם פונקציית ההפעלה מחזירות 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.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 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();

השלבים הבאים

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