דף זה תורגם על ידי Cloud Translation API.

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

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

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

Play Core Native SDK הוא חלק ממשפחת ספריות הליבה של Google Play. 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.

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

Download Play Core Native SDK

Before downloading, you must agree to the following terms and conditions.

Terms and Conditions

Last modified: September 24, 2020

By using the Play Core Software Development Kit, you agree to these terms in addition to the Google APIs Terms of Service ("API ToS"). If these terms are ever in conflict, these terms will take precedence over the API ToS. Please read these terms and the API ToS carefully.
For purposes of these terms, "APIs" means Google's APIs, other developer services, and associated software, including any Redistributable Code.
“Redistributable Code” means Google-provided object code or header files that call the APIs.
Subject to these terms and the terms of the API ToS, you may copy and distribute Redistributable Code solely for inclusion as part of your API Client. Google and its licensors own all right, title and interest, including any and all intellectual property and other proprietary rights, in and to Redistributable Code. You will not modify, translate, or create derivative works of Redistributable Code.
Google may make changes to these terms at any time with notice and the opportunity to decline further use of the Play Core Software Development Kit. Google will post notice of modifications to the terms at https://developer.android.com/guide/playcore/license. Changes will not be retroactive.

I have read and agree with the above terms and conditions

Download Play Core Native SDK

play-core-native-sdk-1.15.2.zip

בצע אחת מהפעולות הבאות:
- מתקינים את Android Studio בגרסה 4.0 ואילך. משתמשים בממשק המשתמש של SDK Manager כדי להתקין את Android SDK Platform בגרסה 10.0 (רמת API 29).
- מתקינים את כלי שורת הפקודה של Android SDK ומשתמשים ב-sdkmanager כדי להתקין את Android SDK Platform בגרסה 10.0 (רמת API 29).
כדי להכין את Android Studio לפיתוח מקורי, משתמשים ב-SDK Manager כדי להתקין את CMake ואת Android Native Development Kit (NDK) בגרסה העדכנית ביותר. למידע נוסף על יצירת פרויקטים מקומיים או ייבוא שלהם, קראו את המאמר תחילת העבודה עם NDK.

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

קישור להורדה	גודל	סיכום ביקורת (checksum) SHA-256
	37.8 MiB	56c5408b5b84cd3c18f268395b2cc23d53152dc9b228e979cc81f8b7f121f73c

מעדכנים את הקובץ 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.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"))
    ...
}

מעדכנים את קובצי ה-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 בקובץ 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 כשהמשתמש מבצע פעולה מסוימת (למשל, הקשה על הלחצן Next Level (הרמה הבאה) במשחק), כפי שמוצג בדוגמה הבאה:

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

השלבים הבאים

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