دعوة ترقية Android

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

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

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

يمكن لمصنّعي الأجهزة تفعيل ميزة "حفل الترقية" على أجهزة Android من خلال إرسال نموذج طلب تفعيل ميزة "دعوة ترقية Android".

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

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

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

لتخصيص عملية الترقية، راجِع الإرشادات الواردة في دليل أسلوب دعوة الترقية وأدرِج معلومات التخصيص في ردّ النموذج.

دليل أسلوب دعوة الترقية

استخدِم دليل الأسلوب هذا لتعديل مظهر دعوة الترقية بما يتناسب مع علامتك التجارية (الشاشات والألوان والخطوط). ننصحك بشدة بالحفاظ على الأحجام والبنية قريبة من التصميم الأصلي.

يتضمّن مسار "دعوة الترقية" المكوّنات الثلاثة التالية:

• شاشة البداية
• شاشة الميزات
• شاشة الفيديو الختامي

تساعد صورة متحركة على كل شاشة في شرح كل ميزة.

شاشة البداية

تحتوي شاشة المقدمة على رسم متحرك قصير يرحّب بالمستخدم ويشجّعه على بدء التدفق المعروض على شاشة المقدمة.

التنسيق

تتألف صورة الجهاز المتحركة دائمًا مما يلي:

• خلفية بيضاء وأشكال ملوّنة
• إطار الجهاز
• محتوى واجهة المستخدم

التصميم

إذا اخترت استخدام تصميم Material You، يمكنك استخدام الألوان والأشكال التلقائية المعروضة في المثال.

إذا كنت تستخدم لون علامتك التجارية، تأكَّد من أنّه يتناسب مع خلفية واجهة المستخدم.

حركة

الخيار 1: استخدام ساعة على الشاشة الرئيسية

1. تظهر الأرقام على الشاشة.
2. تنتقل الأرقام إلى المنتصف مع تناقص حجمها. يظهر إطار الهاتف الجوّال.
3. يصغر حجم الهاتف. تبدأ الأشكال في الظهور على الشاشة.
4. اكتملت الصورة المتحركة. تستمر الأشكال في التحرك بلطف.

الخيار 2: عدم ظهور الساعة على الشاشة الرئيسية

1. يدخل الهاتف المحمول إلى الشاشة.
2. يتحرّك الهاتف إلى المنتصف مع زيادة حجمه. تبدأ الأشكال في الظهور على الشاشة.
3. يصل الهاتف إلى الحد الأقصى للحجم وتستمر الأشكال في التحرك.

شاشة الميزات

تعرض كل شاشة ميزات إحدى الميزات في نظام التشغيل الجديد.

التنسيق

تتألف صورة الجهاز المتحركة دائمًا مما يلي:

• خلفية ملوّنة
• إطار الجهاز
• محتوى واجهة المستخدم

التصميم

• اختَر لونًا للخلفية يتناسب مع محتوى واجهة المستخدم والمظهر العام.
• داخل الشاشات، اضبط أحجام الخطوط التي يمكن قراءتها بسهولة. اضبط أحجام خط أكبر إذا لزم الأمر.

حركة

سجِّل رسومًا متحركة لتدفق كل ميزة، بما في ذلك التفاعلات باللمس. صدِّر التسجيلات كملفات Lottie.

شاشة الفيديو الختامي

تُكمل شاشة النهاية عملية الشراء. يشير ذلك إلى أنّ المستخدمين قد اطّلعوا على جميع الشاشات.

التنسيق

تتألف صورة الجهاز المتحركة دائمًا مما يلي:

• نصف دائرة في الخلفية (بالإضافة إلى أشكال متحرّكة)
• إطار الجهاز
• محتوى واجهة المستخدم

التصميم

• اختَر لون خلفية يتناسب مع محتوى واجهة المستخدم ومظهرها العام.
• استخدِم شكل نصف دائرة.

حركة

اتّبِع تسلسل عرض الصورة المتحركة القياسي لشاشة النهاية:

1. يتحرّك الهاتف الجوّال للأعلى قليلاً.
2. تظهر دائرة في الخلفية.
3. تظهر الأشكال من خلف الهاتف الجوّال.
4. تتطاير الأشكال من الخلفية مثل قصاصات الورق الملوّن.

اختبار خطوات دعوة المستخدمين إلى الترقية

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

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

هناك 3 طرق مختلفة لتفعيل مسار دعوة الترقية: 1. تلقائي 2. بث 3. تم تشغيل حزمة تطوير البرامج (SDK) الخاصة بخدمات Google Play

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

بالنسبة إلى أجهزة المصنّعين الأصليين التي تعمل بنظام gOTA، يكون الدمج تلقائيًا ولا يلزم اتّخاذ أي خطوات لدمج ميزة "دعوة الترقية". عند رصد ترقية رئيسية معلّقة لنظام التشغيل، سيتم إرسال إشعار فوري إلى الجهاز من "خدمات Google Play"، ما يؤدي إلى بدء عملية "دعوة الترقية".

بث Android - إشعار من Google (يُوصى به)

بث التطبيق هو الطريقة الأبسط والأكثر فعالية لدمج مسار ترقية التطبيق ودعوة المستخدمين.

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

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

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

تأكَّد من أنّ ملفات إعداد تطبيقك تستخدم القيم التالية:

• الإصدار 14 من حزمة minSdkVersion أو الإصدارات الأحدث
• الإصدار 28 أو إصدار أحدث من compileSdkVersion
• يستخدم التطبيق الإذن android.permission.RECOVERY

إرسال الإعلان

في ما يلي تعليمات تطبيق (أو رمز) الشركة المصنّعة للجهاز الأصلي لإرسال بث 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). يُستخدَم هذا الحقل لتحديد مسار دعوة الترقية الذي سيتم تنشيطه.

حزمة تطوير البرامج (SDK) لخدمات Play - تشغيل سير العمل فقط

تتيح لك حزمة تطوير البرامج (SDK) التابعة لجهة خارجية بدء عملية دعوة الترقية من تطبيقك أو إشعارات OTA الخاصة بك. استخدِم واجهة برمجة تطبيقات خارجية تابعة لجهة خارجية لتفعيل مسار دعوة الترقية نفسه. لا ننصح كثيرًا باستخدام هذه الطريقة.

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

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

تأكَّد من أنّ ملف الإصدار في تطبيقك يستخدم القيم التالية:

• الإصدار 14 من حزمة minSdkVersion أو الإصدارات الأحدث
• الإصدار 28 أو إصدار أحدث من compileSdkVersion

إعداد تطبيقك

لضبط إعدادات تطبيقك، اتّبِع الخطوات التالية:

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;
}

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

invokeUpgradeInvite

Task<Void> invokeUpgradeInvite();

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

رموز الخطأ

قد يتعذّر تنفيذ كلتا طريقتَي واجهة برمجة التطبيقات مع ظهور استثناء من النوع 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);
             }
           });
   }