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

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

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

Play Core Native SDK הוא חלק ממשפחת Play Core SDK. ערכת ה-SDK לקוד מקורי כוללת קובץ כותרת של C‏, app_update.h, שמקיף את AppUpdateManager מספריית Java Play In-App Update Library. קובץ הכותרת הזה מאפשר לאפליקציה לבצע קריאה ל-API לעדכונים בתוך האפליקציה ישירות מהקוד המקורי.

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

Download Play Core Native SDK

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

Terms and Conditions

Last modified: September 24, 2020
  1. 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.
  2. For purposes of these terms, "APIs" means Google's APIs, other developer services, and associated software, including any Redistributable Code.
  3. “Redistributable Code” means Google-provided object code or header files that call the APIs.
  4. 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.
  5. 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.
Download Play Core Native SDK

play-core-native-sdk-1.15.3.zip

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

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

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

    קישור להורדה גודל סיכום ביקורת (checksum) מסוג SHA-256
    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.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
            ...)
    

איסוף נתונים

ערכת ה-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:

#include "play/app_update.h"

איך מפעילים את ה-API של העדכון בתוך האפליקציה

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

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

  AppUpdateErrorCode error_code =
    AppUpdateManager_init(app->activity->vm, app->activity->clazz);
  if (error_code == APP_UPDATE_NO_ERROR) {
    // You can use the API.
  }
}

בודקים אם יש עדכונים שזמינים

לפני שמבקשים עדכון, צריך לבדוק אם יש עדכון זמין לאפליקציה. AppUpdateManager_requestInfo() מפעילה בקשה אסינכררונית שמרכזת את המידע הנדרש להפעלת תהליך העדכון באפליקציה בשלב מאוחר יותר. הפונקציה מחזירה את הערך APP_UPDATE_NO_ERROR אם הבקשה מתחילה בהצלחה.

AppUpdateErrorCode error_code = AppUpdateManager_requestInfo()

if (error_code == APP_UPDATE_NO_ERROR) {
    // The request has successfully started, check the result using
    // AppUpdateManager_getInfo.
}

אפשר לעקוב אחרי התהליך המתמשך ואחרי התוצאה של הבקשה באמצעות AppUpdateManager_getInfo(). בנוסף לקוד השגיאה, הפונקציה הזו מחזירה מבנה שקוף מסוג AppUpdateInfo, שאפשר להשתמש בו כדי לאחזר מידע על בקשת העדכון. לדוגמה, אפשר להפעיל את הפונקציה הזו בכל לולאת משחק עד שהיא מחזירה תוצאה שאינה null עבור info:

AppUpdateInfo* info;
GameUpdate() {

   // Keep calling this in every game loop until info != nullptr
   AppUpdateErrorCode error_code = AppUpdateManager_getInfo(&info);

   if (error_code == APP_UPDATE_NO_ERROR && info != nullptr) {
       // Successfully started, check the result in the following functions
   }
...
}

בדיקת העדכון

בנוסף לבדיקה אם יש עדכון זמין, כדאי גם לבדוק כמה זמן עבר מאז שהמשתמש קיבל הודעה על עדכון בפעם האחרונה דרך חנות Play. כך תוכלו להחליט אם להתחיל עדכון גמיש או עדכון מיידי. לדוגמה, אפשר להמתין כמה ימים לפני ששולחים למשתמש עדכון גמיש, וכמה ימים לאחר מכן לפני שדורשים עדכון מיידי.

אפשר להשתמש ב-AppUpdateInfo_getClientVersionStalenessDays() כדי לבדוק את מספר הימים מאז שהעדכון זמין בחנות Play:

int32_t staleness_days = AppUpdateInfo_getClientVersionStalenessDays(info);

בדיקת העדיפות של העדכון

Google Play Developer API מאפשר להגדיר את רמת העדיפות של כל עדכון. כך האפליקציה תוכל להחליט עד כמה להמליץ למשתמש על עדכון. לדוגמה, כדאי להשתמש באסטרטגיה הבאה כדי להגדיר את העדיפות של עדכונים:

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

כדי לקבוע את העדיפות, מערכת Google Play משתמשת בערך שלם בין 0 ל-5, כאשר 0 הוא ברירת המחדל ו-5 הוא העדיפות הגבוהה ביותר. כדי להגדיר את רמת העדיפות של עדכון, משתמשים בשדה inAppUpdatePriority בקטע Edits.tracks.releases ב-Google Play Developer API. כל הגרסאות החדשות שנוספו במהדורה נחשבות לבעלות אותה תעדוף כמו המהדורה. אפשר להגדיר את רמת העדיפות רק במהלך ההשקה של גרסה חדשה, ולא ניתן לשנות אותה מאוחר יותר.

מגדירים את רמת העדיפות באמצעות Google Play Developer API, כפי שמתואר במסמכי התיעוד של Play Developer API. מציינים את העדיפות של העדכון בתוך האפליקציה במשאב Edit.tracks שמוענק בשיטה Edit.tracks: update. הדוגמה הבאה ממחישה את השקת האפליקציה עם קוד הגרסה 88 ו-inAppUpdatePriority 5:

{
  "releases": [{
      "versionCodes": ["88"],
      "inAppUpdatePriority": 5,
      "status": "completed"
  }]
}

בקוד של האפליקציה, אפשר לבדוק את רמת העדיפות של עדכון נתון באמצעות AppUpdateInfo_getPriority():

int32_t priority = AppUpdateInfo_getPriority(info);

התחלת עדכון

אחרי שתאשרו שיש עדכון זמין, תוכלו לבקש עדכון באמצעות AppUpdateManager_requestStartUpdate(). לפני ששולחים בקשה לעדכון, צריך לקבל אובייקט AppUpdateInfo עדכני וליצור אובייקט AppUpdateOptions כדי להגדיר את תהליך העדכון. אובייקט AppUpdateOptions מגדיר אפשרויות לתהליך העדכון באפליקציה, כולל אם העדכון צריך להיות גמיש או מיידי.

בדוגמה הבאה נוצר אובייקט AppUpdateOptions לתהליך עדכון גמיש:

// Creates an AppUpdateOptions configuring a flexible in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_FLEXIBLE, &options);

בדוגמה הבאה נוצר אובייקט AppUpdateOptions לתהליך עדכון מיידי:

// Creates an AppUpdateOptions configuring an immediate in-app update flow.
AppUpdateOptions* options;
AppUpdateErrorCode error_code = AppUpdateOptions_createOptions(APP_UPDATE_TYPE_IMMEDIATE, &options);

האובייקט AppUpdateOptions מכיל גם את השדה AllowAssetPackDeletion שמגדיר אם העדכון יכול למחוק חבילות נכסים במקרה של נפח אחסון מוגבל במכשיר. השדה הזה מוגדר כברירת מחדל כ-false, אבל אפשר להשתמש ב-method‏ AppUpdateOptions_setAssetPackDeletionAllowed() כדי להגדיר אותו כ-true במקום זאת:

bool allow = true;
AppUpdateErrorCode error_code = AppUpdateOptions_setAssetPackDeletionAllowed(options, allow);

אחרי שיוצרים אובייקט AppUpdateInfo עדכני ואובייקט AppUpdateOptions שהוגדר בצורה נכונה, צריך לבצע קריאה ל-AppUpdateManager_requestStartUpdate() כדי לבקש באופן אסינכררוני תהליך עדכון, ולהעביר את פעילות Android‏ jobject כפרמטר האחרון.

AppUpdateErrorCode request_error_code =
AppUpdateManager_requestStartUpdate(info, options, app->activity->clazz);

כדי לפנות משאבים, משחררים מכונות של AppUpdateInfo ו-AppUpdateOptions שכבר אין צורך בהן באמצעות קריאה ל-AppUpdateInfo_destroy() ול-AppUpdateOptions_destroy(), בהתאמה.

AppUpdateInfo_destroy(info);
AppUpdateOptions_destroy(options);

בתהליך עדכון מיידי, מוצג למשתמשים ב-Google Play דף אישור. כשהמשתמש מאשר את הבקשה, Google Play מורידים ומתקינים את העדכון באופן אוטומטי בחזית, ואז מפעילים מחדש את האפליקציה בגרסה המעודכנת אם ההתקנה הושלמה.

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

AppUpdateStatus status = AppUpdateInfo_getStatus(info);
if (status == APP_UPDATE_DOWNLOADED) {
    AppUpdateErrorCode error_code = AppUpdateManager_requestCompleteUpdate();
    if (error_code != APP_UPDATE_NO_ERROR)
    {
      // There was an error while completing the update flow.
    }
}

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

טיפול בשגיאות

בקטע הזה מתוארים פתרונות לשגיאות נפוצות שמצוינות על ידי ערכים ספציפיים של AppUpdateErrorCode:

  • קוד השגיאה -110, APP_UPDATE_INITIALIZATION_NEEDED מציין שה-API לא הופעל בהצלחה. קוראים ל-AppUpdateManager_init() כדי לאתחל את ה-API.
  • קוד השגיאה -4, APP_UPDATE_INVALID_REQUEST מציין שחלק מהפרמטרים של בקשת תהליך העדכון בפורמט שגוי. מוודאים שהאובייקטים AppUpdateInfo ו-AppUpdateOptions הם לא null ושהפורמט שלהם תקין.
  • קוד השגיאה -5, APP_UPDATE_UNAVAILABLE מציין שאין עדכון רלוונטי זמין. מוודאים שלגרסת היעד יש את אותו שם חבילה, מזהה אפליקציה ומפתח חתימה. אם יש עדכון זמין, מנקים את המטמון של האפליקציה ומפעילים שוב את AppUpdateManager_requestAppUpdateInfo() כדי לרענן את AppUpdateInfo.
  • קוד השגיאה -6, APP_UPDATE_NOT_ALLOWED מציין שסוג העדכון שצוין באובייקט AppUpdateOption אסור. לפני שמתחילים את תהליך העדכון, צריך לבדוק אם אובייקט AppUpdateInfo מציין שסוג העדכון מותר.

השלבים הבאים

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