دعوة ترقية 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: إشعار من Google (خيار يُنصَح به)

يُعدّ بث التطبيق الطريقة الأبسط والأكثر فعالية لدمج مسار "دعوة الترقية".

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

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

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

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

• الإصدار 14 من minSdkVersion أو الإصدارات الأحدث
• الإصدار 28 من compileSdkVersion أو الإصدارات الأحدث
• الإذن android.permission.RECOVERY من usesPermission

إرسال البث

في ما يلي تعليمات تطبيق مصنّع المعدات الأصلية (أو الرمز) لإرسال بث 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. أضِف الاعتمادات لحزمة تطوير البرامج (SDK) الخاصة بـ Google Growth إلى ملف Gradle على مستوى التطبيق في الوحدة، وعادةً ما يكون app/build.gradle:

   dependencies {
    implementation files(&<#39;PATH_TO_BI>NARY/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();

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

رموز الخطأ

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