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

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

סקירה כללית על 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.

אם הפונקציה מצליחה, גם פונקציית הבקשה וגם פונקציית ההפעלה מחזירות את הערך 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 של האפליקציה, כפי שמתואר בהמשך:

   Groovy

       // 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.2.2'
           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.2.2")
       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
           ...)
   

איסוף נתונים

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

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

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

חשוב לדעת: איסוף הנתונים הזה קשור לשימוש שלכם ב-Play Core Native SDK, והשימוש של Google בנתונים שנאספים הוא נפרד ולא תלוי באיסוף של Google של יחסי התלות בספריות שהוגדרו ב-Gradle כשאתם מעלים את חבילת האפליקציה ל-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();

השלבים הבאים

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