دعوة لترقية Android

دعوة الترقية عبارة عن تدفق مستخدم يعرض الميزات الرئيسية الجديدة المضمنة في الترقية الرئيسية الحالية لنظام التشغيل Android.

يهدف التدفق إلى المساعدة في إقناع المستخدمين بترقية أجهزتهم إلى أحدث إصدار من نظام التشغيل.

بمجرد حصول الجهاز على ترقية لنظام التشغيل في انتظار موافقة المستخدم، يتلقى المستخدمون إشعارًا مباشرًا يعرض الميزات الجديدة ويدعوهم لإجراء الترقية.

لتمكين Upgrade Invite لنظام التشغيل Android الخاص بك، قم بالتسجيل باستخدام نموذج طلب تنشيط Android Upgrade Invite .

تخصيص تجربة دعوة الترقية

يمكنك تخصيص تجربة "دعوة الترقية" بالطرق التالية:

• إزالة الميزات غير ذات الصلة.
• قم بتحديث اللغة في الكتل النصية.
• قم بتعديل الرسوم المتحركة والألوان والخطوط لتتناسب مع علامتك التجارية.

لتخصيص التدفق، راجع الإرشادات الموجودة في دليل نمط دعوة ترقية وقم بتضمين معلومات التخصيص الخاصة بك في نموذج طلب تنشيط دعوة ترقية Android .

اختبر تدفق دعوة الترقية

1. على جهاز Android، انتقل إلى: الإعدادات > Google > تصحيح أخطاء الطرف الترقية .
2. قم بإعداد المشغل لـ Upgrade Invite لنظام تشغيل الجهاز ذي الصلة (اعتمادًا على إصدار نظام التشغيل الحالي لديك، وتدفق دعوة الترقية المحدد للاختبار. إما:
   1. انقر فوق كتابة ترقية وهمية (الإصدار الحالي) . (على سبيل المثال، إذا كنت تستخدم نظام التشغيل Android 13، فسيؤدي ذلك إلى تشغيل تدفق اختبار Android 13)
   2. انقر فوق كتابة في انتظار الترقية (الإصدار الحالي + 1) . (على سبيل المثال، إذا كنت تستخدم نظام التشغيل Android 12، فسيؤدي ذلك إلى تشغيل تدفق اختبار Android 13)
   3. انقر فوق الإبلاغ عن ترقية نظام التشغيل
3. إما أن تنقر على الإشعار المستلم، أو أنقر على فتح دعوة الترقية.

خيارات التشغيل لدعوة الترقية

هناك 3 طرق مختلفة لتشغيل تدفق دعوة الترقية: 1. تلقائي 2. البث 3. تشغيل Play Services SDK

تلقائي - تم تشغيل إشعار Google (لأجهزة تشغيل goTA فقط)

بالنسبة لأجهزة OEM التي تقوم بتشغيل goTA، يكون التكامل تلقائيًا ولا يلزم وجود خطوات تكامل Upgrade Invite. بمجرد اكتشاف ترقية رئيسية معلقة لنظام التشغيل، سيؤدي ذلك إلى إرسال إشعار دفع إلى الجهاز من خدمات Google Play، مما يؤدي إلى تدفق دعوة الترقية.

Android Broadcast - تم تشغيل إشعار Google (مستحسن)

يُعد بث التطبيق الطريقة الأبسط والموصى بها لدمج تدفق دعوة الترقية.

يمكّنك جهاز استقبال البث من تشغيل تدفق دعوة الترقية من تطبيقك باستخدام رسالة بث. يرسل البث إشعارًا فوريًا إلى الجهاز من خدمات Google Play، مما يؤدي إلى تدفق دعوة الترقية.

متطلبات البث

لإعداد تطبيقك، أكمل الخطوات الواردة في الأقسام التالية.

تأكد من أن ملفات تكوين تطبيقك تستخدم القيم التالية:

• إصدار minSdk يبلغ 14 أو أعلى
• إصدار CompilSdk يبلغ 28 أو أعلى
• استخدامات إذن android.permission.RECOVERY

أرسل البث

انظر أدناه الإرشادات الخاصة بتطبيق OEM (أو الكود) لإرسال بث Android لتشغيل إشعار الدفع:

1. إرسال البث مع العمل.

   com.google.android.gms.growth.upgradeparty.upgradeinvite.ACTION_SYSTEM_UPDATE
   

2. أضف الحزمة com.google.android.gms إلى البث.

   com.google.android.gms
   

متطلبات إضافية

يمكّن تدفق دعوة الترقية أيضًا المستخدمين من إجراء ترقية نظام التشغيل مباشرة من التدفق.

لكي ينجح هذا، اكشف عن غرض مخصص يمكن أن تستدعيه Google من تدفق دعوة الترقية الذي يؤدي إلى تنزيل التحديث.

مثال على استخدام البث

راجع المثال التالي لبث التطبيق:

Context context = getApplicationContext();
Intent upgradeInviteIntent = new Intent()
  .setAction( "com.google.android.gms.growth.upgradeparty.upgradeinvite.ACTION_SYSTEM_UPDATE")
  .setPackage("com.google.android.gms");
  .putExtra("com.google.android.gms.growth.upgradeparty.upgradeinvite.EXTRA_PENDING_ANDROID_OS_VERSION_NUMBER", 14);

context.sendBroadcast(updateIntent);

قيمة المفتاح EXTRA_PENDING_ANDROID_OS_VERSION_NUMBER هي عدد صحيح يشير إلى إصدار نظام التشغيل المعلق (في هذا المثال، إصدار Android الذي سيتم تثبيته هو 14). يُستخدم هذا لتحديد تدفق دعوة الترقية الذي سيتم تشغيله.

Play Services SDK - تشغيل التدفق فقط

يمكّنك SDK التابع لجهة خارجية من تشغيل تدفق دعوة الترقية من تطبيقك أو إشعارات OTA الخاصة بك. استخدم واجهة برمجة التطبيقات الخارجية لجهة خارجية لتنشيط تدفق دعوة الترقية نفسه. هذه الطريقة أقل الموصى بها.

المتطلبات الأساسية

لإعداد تطبيقك، أكمل الخطوات الواردة في الأقسام التالية.

تأكد من أن ملف إنشاء تطبيقك يستخدم القيم التالية:

• إصدار minSdk يبلغ 14 أو أعلى
• إصدار CompilSdk يبلغ 28 أو أعلى

قم بتكوين التطبيق الخاص بك

لتكوين تطبيقك:

1. Extract the library from the provided .zip file, and place it in your

مخزن. 2. أضف تبعيات Google Growth SDK إلى ملف Gradle على مستوى التطبيق الخاص بوحدتك، عادةً app/build.gradle :

   dependencies {
    implementation files('<PATH_TO_BINARY>/play-services-growth-16.1.0-eap04.aar')
   }

1. لتوفير تبعيات العميل، قم بتضمين المكتبات التالية:

   com.google.android.gms:play-services-base:18.0.1
   com.google.android.gms:play-services-basement:18.0.0
   com.google.android.gms:play-services-tasks:18.0.1
   

تهيئة واجهة برمجة التطبيقات

1. لتهيئة العميل، استخدم فئة UpgradeParty:

   import com.google.android.gms.growth.UpgradeParty;
   UpgradeParty.getClient(activity);
   

2. يجب أن تكون معلمة النشاط هي كائن النشاط البادئ.

وظائف واجهة برمجة التطبيقات

يعرض UpgradePartyClient الناتج الوظائف التالية.

isEligibleForUpgradeInvite

import com.google.android.gms.growth.UpgradeInviteEligibilityParams;

Task<Boolean> isEligibleForUpgradeInvite(UpgradeInviteEligibilityParams params);

/** Contains parameters for the eligibility query. */
class UpgradeInviteEligibilityParams {


/** Integer indicating the pending OS version (in this example, the Android version to be installed is 14). This is used to determine which Upgrade Invite flow will be triggered. */
  int pendingAndroidOsVersionNumber;
}

إرجاع مهمة تتحقق بشكل غير متزامن مما إذا كان المستخدم مؤهلاً لدعوة الترقية. تشير القيمة المنطقية الناتجة إلى ما إذا كان المستخدم مؤهلاً أم لا.

استدعاءUpgradeInvite

Task<Void> invokeUpgradeInvite();

استدعاء نشاط دعوة الترقية. يشير _Task _object الناتج إلى ما إذا كان قد حدث خطأ عند بدء النشاط.

رموز الخطأ

قد تفشل كلتا طريقتي API باستثناء النوع com.google.android.gms.common.api.ApiException . في مثل هذه الحالات، من المتوقع أن يقوم المتصل بإعادة المحاولة في وقت لاحق. تتضمن رموز الحالة المشتركة المتوقعة ) ما يلي:

• INTERNAL_ERROR - لأي خطأ في تدفق المنطق الأساسي
• TIMEOUT - إذا تعذر التعامل مع الطلب في الوقت المناسب
• API_NOT_CONNECTED - عندما لا تكون واجهة برمجة التطبيقات متاحة (أي أن وحدة UpgradeParty ليست جاهزة بعد)
• NETWORK_ERROR - تعذرت معالجة الطلب بسبب أخطاء في الشبكة
• DEVELOPER_ERROR - لا يُسمح لحزمة الاتصال بالوصول إلى UpgradeParty API

مثال على استخدام SDK

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import com.google.android.gms.growth.UpgradeParty;
import com.google.android.gms.growth.UpgradePartyClient;

public class SampleActivity extends Activity {

 @Override
 protected void onCreate(Bundle savedInstanceState) {
   super.onCreate(savedInstanceState);
   final UpgradePartyClient client = UpgradeParty.getClient(this);

   // Hide the invocation button initially
   View startUpgradeInviteButton = findViewById(R.id.__some_button__);
   startUpgradeInviteButton.setVisibility(View.GONE);

   // Register an onClick handler to invoke the Upgrade Party Activity
   startUpgradeInviteButton
       .setOnClickListener(
           view -> {
             client
                 .invokeUpgradeInvite()
                 .addOnCompleteListener(
                     task -> {
                       if (!task.isSuccessful()) {
                         // Do something with error, see task.getException()
                       }
                     });
           });
   }

   // Check if eligible for an Upgrade Party
   client
       .isEligibleForUpgradeInvite()
       .addOnCompleteListener(
           task -> {
             if (!task.isSuccessful()) {
               // Do something with error, see task.getException()
             } else {
                  // Show/Hide invocation button, based on the result
                  int visibility = 
                        task.getResult() ? View.VISIBLE : View.GONE;
                  startUpgradeInviteButton.setVisibility(visibility);
             }
           });
   }