دعوة ترقية Android

دعوة الترقية هي تدفق للمستخدمين يعرض الميزات الجديدة الرئيسية المضمّنة في الترقية الرئيسية المتاحة حاليًا لنظام التشغيل 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 أو إصدار أحدث
• الإصدار 28 أو إصدار أعلى من البيانات المجمَّعةSdkVersion

إعداد تطبيقك

لضبط إعدادات تطبيقك، يُرجى اتّباع الخطوات التالية:

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

تعرِض مهمة تحقّق بشكل غير متزامن مما إذا كان المستخدم مؤهلاً لتلقّي دعوة 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);
             }
           });
   }