‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

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

הורדה Play Core Native SDK

לפני ההורדה, עליכם לאשר את התנאים וההגבלות הבאים.

תנאים והגבלות

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.

קראתי את התנאים וההגבלות שלמעלה ואני מסכים/ה להם

הורדה Play Core Native SDK

play-core-native-sdk-1.16.0.zip

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

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

מעדכנים את קובצי ה-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 "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, שבו אפשר להשתמש כדי לאחזר מידע על בקשת העדכון. לדוגמה, יכול להיות שתרצו לקרוא לפונקציה הזו בכל game loop עד שהיא תחזיר תוצאה שאינה 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);

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

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

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

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

מגדירים את העדיפות באמצעות ממשק ה-API של Google Play למפתחים, כפי שמתואר במסמכי התיעוד של ממשק ה-API של Play למפתחים. מציינים את העדיפות של עדכון לאפליקציה במשאב Edit.tracks שמועבר ב-method‏ 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 Activity 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 לא ריקים ושהפורמט שלהם תקין.
קוד השגיאה -5, APP_UPDATE_UNAVAILABLE מציין שאין עדכון רלוונטי זמין. חשוב לוודא שלגרסת היעד יש את אותו שם חבילה, מזהה אפליקציה ומפתח חתימה. אם יש עדכון זמין, צריך לנקות את המטמון של האפליקציה ולהתקשר שוב אל AppUpdateManager_requestAppUpdateInfo() כדי לרענן את AppUpdateInfo.
קוד השגיאה -6, APP_UPDATE_NOT_ALLOWED מציין שסוג העדכון שצוין באובייקט AppUpdateOption לא מותר. לפני שמתחילים את תהליך העדכון, בודקים אם האובייקט AppUpdateInfo מציין שסוג העדכון מותר.

השלבים הבאים

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

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

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

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

הורדה Play Core Native SDK

תנאים והגבלות

מגניב

Kotlin

איסוף נתונים

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

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

בדיקת עדכניות העדכון

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

התחלת עדכון

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

השלבים הבאים

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