دعوة ترقية Android

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

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

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

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

دليل أسلوب الدعوات لإصدار القنوات الجديدة

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

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

• شاشة البداية
• شاشة العرض
• شاشة النهاية

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

شاشة البداية

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

التنسيق

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

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

التصميم

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

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

الحركة

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

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

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

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

شاشة العرض

تُبرز كل شاشة ميزة في نظام التشغيل الجديد.

التنسيق

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

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

التصميم

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

الحركة

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

شاشة النهاية

تكمل شاشة النهاية هذه العملية. ويشير ذلك إلى المستخدمين بأنّهم اجتازوا جميع الشاشات.

التنسيق

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

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

التصميم

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

الحركة

اتّبِع الخطوات المعتادة لإنشاء صورة متحركة في شاشة النهاية:

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

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

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

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

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

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

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

Android Broadcast - Google triggered notification (Recommended)

إنّ البث المباشر للتطبيقات هو أبسط طريقة يُنصح بها لدمج مسار الترقية الدعوة.

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

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

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

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

• الإصدار 14 من حزمة minSdkVersion أو إصدار أحدث
• ‫compileSdkVersion‏ 28 أو إصدار أحدث
• يستخدم الإذن 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 أو إصدار أحدث
• ‫compileSdkVersion‏ 28 أو إصدار أحدث

ضبط إعدادات تطبيقك

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

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

المستودع. ‫2- أضِف ملفات الاعتماد لحزمة تطوير البرامج (SDK) لبرنامج "نمو Google" إلى ملف 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;
}

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

invokeUpgradeInvite

Task<Void> invokeUpgradeInvite();

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

رموز الخطأ

قد يتعذّر تنفيذ كلتا طريقتَي واجهة برمجة التطبيقات مع ظهور استثناء من النوع com.google.android.gms.common.api.ApiException. وفي هذه الحالات، يُتوقّع من المتصل إعادة المحاولة في وقت لاحق. تشمل رموز الحالة الشائعة المتوقّعة:

• ‫INTERNAL_ERROR: عند حدوث أي خطأ في تسلسل المنطق الأساسي
• انتهاء مهلة: إذا تعذّرت معالجة الطلب في الوقت المناسب
• 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);
             }
           });
   }