دمج ميزة "الإعداد عن بُعد" في الدرس التطبيقي حول ترميز Android

1. مقدمة

تاريخ آخر تعديل: 09/03/2021

ما هي ميزة "الإعداد عن بُعد في Firebase"؟

"الإعداد عن بُعد في Firebase" هي خدمة سحابية تتيح لك تغيير طريقة عمل تطبيقك ومظهره بدون أن يحتاج المستخدمون إلى تنزيل تحديث للتطبيق بدون أي تكلفة. عند استخدام ميزة "الإعداد عن بُعد"، يمكنك إنشاء قيم تلقائية داخل التطبيق تتحكّم في سلوك تطبيقك ومظهره. بعد ذلك، يمكنك لاحقًا استخدام وحدة تحكُّم Firebase أو واجهات برمجة تطبيقات الخلفية لميزة "الإعداد عن بُعد" لإلغاء القيم التلقائية داخل التطبيق لجميع مستخدمي التطبيق أو لشرائح قاعدة المستخدمين. يتحكم تطبيقك في وقت تطبيق التحديثات، ويمكنه البحث عن التحديثات بشكل متكرر وتطبيقها بدون أي تأثير يُذكر في الأداء.

كيف تعمل هذه الميزة؟

تتضمّن ميزة "الإعداد عن بُعد" مكتبة برامج تتعامل مع مهام مهمة مثل استرجاع قيم المَعلمات وتخزينها مؤقتًا، مع منحك إمكانية التحكّم في وقت تفعيل القيم الجديدة من أجل التأثير في تجربة المستخدم الخاصة بتطبيقك. يتيح لك ذلك حماية تجربة تطبيقك من خلال التحكّم في توقيت تنفيذ أي تغييرات.

توفِّر طرق get في مكتبة برامج "الإعداد عن بُعد" نقطة وصول واحدة لقيم المَعلمات. يحصل تطبيقك على قيم من جهة الخادم باستخدام المنطق نفسه الذي يستخدمه للحصول على القيم التلقائية داخل التطبيق، لذلك يمكنك إضافة إمكانات "الإعداد عن بُعد" إلى تطبيقك بدون كتابة الكثير من الرموز.

لإلغاء القيم التلقائية داخل التطبيق، يمكنك استخدام وحدة تحكُّم Firebase أو واجهات برمجة تطبيقات الخلفية لميزة "الإعداد عن بُعد" لإنشاء مَعلمات تحمل الأسماء نفسها للمَعلمات المستخدَمة في تطبيقك. بالنسبة إلى كل مَعلمة، يمكنك ضبط قيمة تلقائية من جهة الخادم لإلغاء القيمة التلقائية داخل التطبيق، ويمكنك أيضًا إنشاء قيم شرطية لإلغاء القيمة التلقائية داخل التطبيق لمثيلات التطبيق التي تستوفي شروطًا معيّنة. يوضّح هذا الرسم كيفية منح الأولوية لقيم المَعلمات في خلفية "الإعداد عن بُعد" وفي تطبيقك:

المعلومات التي ستطّلع عليها

• طريقة تنفيذ ميزة "الإعداد عن بُعد في Firebase"
• كيفية استخدام ميزة "الإعداد عن بُعد في Firebase" لتغيير القيم بدون تحديث تطبيقك

المتطلبات

• أحدث إصدار من "استوديو Android"
• حساب على Firebase
• (يُنصح به، ولكنّه اختياري) جهاز Android فعلي لتشغيل تطبيقك
• معرفة أساسية بلغة Java أو Kotlin

2. بدء الإعداد

(اختياري) تنزيل نموذج الرمز

في هذا الدرس التطبيقي حول الترميز، ستنشئ تطبيقك التجريبي، ولكن إذا كنت تريد الاطّلاع على نموذج التطبيق الحالي وتشغيله، يمكنك تنزيل نموذج رمز البدء السريع.

انقر على الزر التالي لتنزيل جميع الرموز الخاصة بهذا الدرس التطبيقي حول الترميز:

تنزيل رمز المصدر

فك ضغط ملف ZIP الذي تم تنزيله. سيؤدي هذا الإجراء إلى فك ضغط مجلد جذر باسم quickstart-android-master.

...أو استنساخ مستودع جيت هب من سطر الأوامر.

$ git clone https://github.com/firebase/quickstart-android.git

يحتوي المستودع على مجلدات متعددة. سنستخدم مجلد config.

(اختياري) استيراد نموذج الرمز

افتح "استوديو Android" واختَر استيراد مشروع في شاشة الترحيب. بعد ذلك، افتح المجلد الذي تم تنزيله واختَر المجلد config . بعد ذلك، انقر على "فتح".

إنشاء مشروع Android جديد

1. بدء مشروع جديد في "استوديو Android"
2. اختيار "النشاط الأساسي"
3. في قسم "إعداد مشروعك" الشاشة:
4. قم بتسمية مشروعك. سيتم إنشاء اسم الحزمة وموقع الحفظ لك تلقائيًا.
5. اللغة: Java
6. الحد الأدنى للإصدار 16 من حزمة تطوير البرامج (SDK)

3- إضافة Firebase و"إحصاءات Firebase" إلى مشروع Android

إنشاء مشروع على Firebase

قبل أن تتمكن من إضافة Firebase إلى تطبيقك على Android، يجب إنشاء مشروع Firebase لربطه بتطبيق iOS. انتقِل إلى مقالة فهم مشاريع Firebase للاطّلاع على مزيد من المعلومات عن مشاريع Firebase.

1. في وحدة تحكُّم Firebase، انقر على إضافة مشروع، ثم اختَر اسم مشروع أو أدخِله.

إذا كان لديك مشروع حالي على Google Cloud Platform (GCP)، يمكنك اختيار المشروع من القائمة المنسدلة لإضافة موارد Firebase إلى هذا المشروع.

2. (اختياري) إذا كنت تنشئ مشروعًا جديدًا، يمكنك تعديل رقم تعريف المشروع.

يعيّن Firebase تلقائيًا معرّفًا فريدًا لمشروعك في Firebase. انتقِل إلى صفحة "فهم مشاريع Firebase" للتعرّف على كيفية استخدام Firebase لرقم تعريف المشروع.

ملاحظة: بعد إدارة Firebase للموارد لمشروعك في Firebase، لا يمكنك تغيير رقم تعريف مشروعك. لاستخدام معرّف محدّد، عليك تعديل رقم تعريف مشروعك أثناء خطوة الإعداد هذه.

3. انقر على متابعة.
4. يمكنك إعداد "إحصاءات Google" لمشروعك، ما يمكّنك من الحصول على أفضل تجربة باستخدام أي من منتجات Firebase التالية:

• Firebase Crashlytics
• توقعات Firebase
• المراسلة عبر السحابة الإلكترونية من Firebase
• المراسلة داخل تطبيق Firebase
• الإعداد عن بُعد في Firebase
• اختبار A/B من Firebase

اختَر استخدام حساب حالي على "إحصاءات Google" أو إنشاء حساب جديد عندما يُطلب منك ذلك. إذا اختَرت إنشاء حساب جديد، اختَر موقع إعداد التقارير في "إحصاءات Google"، ثم اقبل إعدادات مشاركة البيانات وبنود "إحصاءات Google" لمشروعك.

5. انقر على إنشاء مشروع (أو إضافة Firebase إذا كنت تستخدم مشروع Google Cloud Platform حالي).

يوفّر Firebase تلقائيًا الموارد لمشروعك على Firebase. عند اكتمال العملية، سيتم نقلك إلى صفحة النظرة العامة لمشروع Firebase في وحدة تحكُّم Firebase.

تسجيل تطبيقك في Firebase

بعد إنشاء مشروع على Firebase، يمكنك إضافة تطبيق Android إليه.

انتقِل إلى قسم فهم مشاريع Firebase للاطّلاع على مزيد من المعلومات عن أفضل الممارسات والاعتبارات المتعلقة بإضافة التطبيقات إلى مشروع Firebase، بما في ذلك كيفية التعامل مع صيغ إنشاء متعددة.

1. انتقِل إلى "وحدة تحكُّم Firebase".
2. في أعلى صفحة "نظرة عامة على المشروع"، انقر على رمز Android لبدء سير عمل الإعداد. إذا سبق وأضفت تطبيقًا إلى مشروع Firebase، انقر على "إضافة تطبيق" لعرض خيارات النظام الأساسي.
3. أدخل اسم حزمة التطبيق في حقل اسم حزمة Android.
4. (اختياري) أدخِل اسم التطبيق.
5. اترك حقل SHA-1 فارغًا لأن SHA-1 ليس مطلوبًا لهذا المشروع.
6. انقر على تسجيل التطبيق.

إضافة ملف إعداد Firebase

سيُطلب منك بعد ذلك تنزيل ملف إعداد يحتوي على جميع بيانات Firebase الوصفية اللازمة لتطبيقك. انقر على تنزيل google-services.json للحصول على ملف إعداد Android (google-services.json) في Firebase.

في ملف Gradle على مستوى المشروع (build.gradle)، أضِف قواعد لتضمين المكوّن الإضافي لتطبيق Gradle في خدمات Google. تأكَّد من أنّ لديك مستودع Maven من Google أيضًا.

Build.gradle على مستوى المشروع (<project>/build.gradle):

buildscript {

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
  }

  dependencies {
    // ...

    // Add the following line:
    classpath 'com.google.gms:google-services:4.3.5'  // Google Services plugin
  }
}

allprojects {
  // ...

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
    // ...
  }
}

في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً app/build.gradle)، طبِّق المكوِّن الإضافي لنظام Gradle لخدمات Google:

Build.gradle على مستوى التطبيق (<project>/<app-module>/build.gradle):

تطبيق المكون الإضافي: 'com.android.application'

// إضافة السطر التالي:

تطبيق المكوّن الإضافي: 'com.google.gms.google-services' // المكوّن الإضافي لخدمات Google

android {

// ...

}

إضافة حزمة تطوير البرامج (SDK) لمنصة Firebase إلى تطبيقك على Android

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

(تم تنفيذ هذا الإجراء من خلال نموذج رمز البدء السريع)

باستخدام Firebase Android BoM، وضِّح الاعتماد على مكتبة "الإعداد عن بُعد" في أجهزة Android في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً ما يكون app/build.gradle). باستخدام نظام Android BoM من Firebase، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Android في Firebase.

وكجزء من إعداد "إحصاءات Google"، عليك أيضًا إضافة حزمة تطوير البرامج (SDK) لمنصّة Firebase الخاصّة بخدمة "إحصاءات Google" إلى تطبيقك. ضمن التبعيات، أضف التعليمة البرمجية التالية:

app/build.gradle

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:26.6.0')

    // Declare the dependencies for the Remote Config and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-config'
    implementation 'com.google.firebase:firebase-analytics'
}

مزامنة مشروعك مع ملفات Gradle

للتأكُّد من توفُّر جميع الاعتماديات لتطبيقك، عليك مزامنة مشروعك مع ملفات Gradle من خلال اختيار ملف >. مزامنة المشروع مع ملفات Gradle

4. مراجعة المكوّنات الرئيسية لميزة "الإعداد عن بُعد"

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

1. الحصول على عنصر "الإعداد عن بُعد" في نمط "سينغلتون"

يمكنك الحصول على النسخة الافتراضية لعنصر "الإعداد عن بُعد" وضبط الحد الأدنى للفاصل الزمني للاسترجاع للسماح بإعادة التحميل بشكل متكرّر:

MainActivity.java

mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance();
FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder()
        .setMinimumFetchIntervalInSeconds(3600)
        .build();
mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);

يُستخدم كائن "سينغلتون" لتخزين قيم المَعلمات التلقائية داخل التطبيق واسترجاع قيم المَعلمات المعدَّلة من الخلفية والتحكّم في وقت توفُّر القيم التي تم استرجاعها لتطبيقك.

أثناء التطوير، يُنصح بضبط حدّ أدنى منخفض نسبيًا للفاصل الزمني للجلب. راجِع المقالة تقييد للاطّلاع على مزيد من المعلومات.

من خلال وضع ذلك في MainActivity.java، سيتم استرجاع القيم الجديدة عند بدء تشغيل التطبيق. يجلب النموذج Quickstart قيم المعلمات المحدثة عند الضغط على الزر.

2- ضبط قيم المَعلمات التلقائية داخل التطبيق

يمكنك ضبط قيم المَعلمات التلقائية داخل التطبيق في عنصر "الإعداد عن بُعد"، لكي يعمل تطبيقك على النحو المطلوب قبل اتصاله بواجهة "الإعداد عن بُعد"، وبالتالي تتوفّر القيم التلقائية في حال عدم ضبط أيّ من هذه القيم في الخلفية.

يمكنك تحديد مجموعة من أسماء المَعلمات وقيم المَعلمات التلقائية باستخدام عنصر خريطة أو ملف موارد XML مخزَّن في مجلد res/xml في تطبيقك. يستخدم نموذج تطبيق البدء السريع لميزة "الإعداد عن بُعد" ملف XML لتحديد أسماء وقيم المَعلمات التلقائية. في ما يلي كيفية إنشاء ملف XML بنفسك:

1. أنشِئ مجلد "xml" ضمن المجلد "res".

2. انقر بزر الماوس الأيمن على مجلد "xml" الذي تم إنشاؤه حديثًا وأنشِئ ملفًا.

3. اضبط القيم التلقائية. في القسم التالي، ستحاول تغيير القيم التلقائية في ملف XML السريع للتفعيل عن بُعد.
4. أضف هذه القيم إلى كائن "الإعداد عن بُعد" باستخدام setDefaultsAsync(int)، كما هو موضّح:

MainActivity.java

mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

3- الحصول على قيم المَعلمات لاستخدامها في تطبيقك

يمكنك الآن الحصول على قيم المَعلمات من كائن "الإعداد عن بُعد". في حال ضبط القيم في الخلفية، جلبها ثم تفعيلها، تصبح هذه القيم متوفّرة لتطبيقك. بخلاف ذلك، يمكنك الحصول على قيم المَعلمات داخل التطبيق التي يتم ضبطها باستخدام setDefaultsAsync(int). للحصول على هذه القيم، اطلب الطريقة المُدرجة أدناه التي ترتبط بنوع البيانات الذي يتوقعه تطبيقك، مع تقديم مفتاح المَعلمة كوسيطة:

• getBoolean()
• getDouble()
• getLong()
• getString()

4- استرجاع القيم وتفعيلها

1. لاسترجاع قيم المَعلمات من خلفية "الإعداد عن بُعد"، يجب استدعاء طريقة fetch(). يتم استرجاع أي قيم ضبطتها في الخلفية وتخزينها في عنصر "الإعداد عن بُعد".
2. لإتاحة قيم المَعلمات التي تم استرجاعها لتطبيقك، يمكنك استدعاء الإجراء activate(). بالنسبة إلى الحالات التي تريد فيها استرجاع القيم وتفعيلها في استدعاء واحد، يمكنك استخدام طلب meetAndActivate() لاسترجاع القيم من خلفية "الإعداد عن بُعد" وإتاحتها للتطبيق:

MainActivity.java

mFirebaseRemoteConfig.fetchAndActivate()
        .addOnCompleteListener(this, new OnCompleteListener<Boolean>() {
            @Override
            public void onComplete(@NonNull Task<Boolean> task) {
                if (task.isSuccessful()) {
                    boolean updated = task.getResult();
                    Log.d(TAG, "Config params updated: " + updated);
                    Toast.makeText(MainActivity.this, "Fetch and activate succeeded",
                            Toast.LENGTH_SHORT).show();

                } else {
                    Toast.makeText(MainActivity.this, "Fetch failed",
                            Toast.LENGTH_SHORT).show();
                }
                displayWelcomeMessage();
            }
        });

ولأنّ قيم المَعلمات المعدّلة هذه تؤثّر في سلوك تطبيقك ومظهره، يجب تفعيل القيم التي تم استرجاعها في وقت يضمن توفير تجربة سلسة للمستخدم، مثلاً في المرة التالية التي يفتح فيها المستخدم تطبيقك. يمكنك الاطّلاع على استراتيجيات التحميل في ميزة "الإعداد عن بُعد" للحصول على مزيد من المعلومات والأمثلة.

ملاحظة: إذا لم يتم إنشاء تطبيقك باستخدام Gradle، يجب عليك إضافة مورد سلسلة google_app_id الصحيح يدويًا إلى تطبيقك حتى يمكن إعداد ميزة "الإعداد عن بُعد". عادةً ما يضيف مكوّن Gradle الإضافي google-services هذا الإعداد تلقائيًا، ولكن يمكنك العثور على القيمة المناسبة في ملف google-services.json الذي يمكنك تنزيله من وحدة تحكُّم Firebase. لمزيد من المعلومات عن الحصول على القيمة google_app_id من ملف google-services.json، يمكنك الاطّلاع على مقالة معالجة ملف JSON.

تقييد البيانات

في حال جلب أحد التطبيقات مرات كثيرة جدًا خلال فترة زمنية قصيرة، يتم تقييد طلبات الجلب، وتعرض حزمة تطوير البرامج (SDK) القيمة FirebaseRemoteConfigFetchThrottledException. قبل الإصدار 17.0.0 من حزمة تطوير البرامج (SDK)، كان الحدّ الأقصى المسموح به هو 5 طلبات جلب خلال 60 دقيقة (تفرض الإصدارات الأحدث حدودًا أكثر تساهلاً).

أثناء تطوير التطبيق، قد تحتاج إلى استرجاع الإعدادات وتفعيلها بشكلٍ متكرر جدًا (عدة مرات في الساعة) للسماح لك بالتكرار السريع أثناء تطوير تطبيقك واختباره. لاستيعاب التكرار السريع لمشروع يضم ما يصل إلى 10 مطوّرين، يمكنك إعداد عنصر FirebaseRemoteConfigSettings مؤقتًا مع حد أدنى منخفض للفاصل الزمني للجلب (setMinimumFetchIntervalInSeconds) في تطبيقك.

الحد الأدنى التلقائي للفاصل الزمني للاسترجاع في ميزة "الإعداد عن بُعد" هو 12 ساعة، ما يعني أنّه لن يتم استرجاع الإعدادات من الخلفية أكثر من مرة خلال 12 ساعة، بغض النظر عن عدد طلبات الجلب التي يتم إجراؤها فعلاً. وعلى وجه التحديد، يتم تحديد الحد الأدنى للفاصل الزمني للاسترجاع بالترتيب التالي:

1. المَعلمة في fetch(long)
2. المَعلمة في FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
3. القيمة التلقائية التي تبلغ 12 ساعة

لضبط الحد الأدنى للفاصل الزمني للاسترجاع على قيمة مخصّصة، استخدِم FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long).

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

5- تغيير سلوك التطبيق باستخدام ميزة "الإعداد عن بُعد"

تغيير المَعلمات التلقائية داخل التطبيق

افتح res/xml/remote_config_defaults.xml وغيِّر القيم التلقائية إلى خيار آخر.

res/xml/remote_config_defaults.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- START xml_defaults -->
<defaultsMap>
    <entry>
        <key>loading_phrase</key>
        <value>Fetching config...</value>
    </entry>
    <entry>
        <key>welcome_message_caps</key>
        <value>false</value>
    </entry>
    <entry>
        <key>welcome_message</key>
        <value>Welcome to my awesome app!</value>
    </entry>
</defaultsMap>
    <!-- END xml_defaults -->

التحقّق من تغيير القيمة التلقائية داخل التطبيق

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

3. راجِع رسالة الترحيب في العرض الرئيسي.

ضبط قيم المَعلمات في الواجهة الخلفية لميزة "الإعداد عن بُعد"

لنختبر الآن إرسال القيم من خلال ميزة "الإعداد عن بُعد". باستخدام وحدة تحكُّم Firebase أو واجهات برمجة تطبيقات الخلفية للإعداد عن بُعد، يمكنك إنشاء قيم تلقائية جديدة من جهة الخادم تلغي القيم داخل التطبيق وفقًا للمنطق الشرطي أو استهداف المستخدم المطلوب. يوضِّح هذا القسم خطوات "وحدة تحكُّم Firebase" لإنشاء هذه القيم.

1. افتح وحدة تحكُّم Firebase وافتح مشروعك.
2. اختَر الإعداد عن بُعد من القائمة الجانبية اليمنى في قسم "التفاعل" لعرض لوحة بيانات "الإعداد عن بُعد".
3. ضمن إضافة مَعلمة، أدخِل Parameter key. ضمن Default value، أضِف النص الذي تريده. بعد ذلك، انقر على "إضافة مَعلمة". في هذا الدرس التطبيقي حول الترميز، سنستخدم مفاتيح المَعلمات في ملف res/xml/remote_config_defaults.xml. اطّلِع على الجدول أدناه لمعرفة التفاصيل:

مفتاح المَعلمة	القيمة التلقائية (remote_config_defaults.xml)	الوصف
loading_phrase	جارٍ استرجاع الإعدادات...	String; يتم عرضه عند استرجاع قيم "الإعداد عن بُعد".
welcome_message_caps	خطأ	منطقي؛ إذا كانت القيمة هي true، سيتم تغيير إدخال website_message إلى جميع الأحرف الكبيرة.
welcome_message	مرحبًا بك في تطبيقي الرائع!	String; رسالة الترحيب

مثال على لقطة شاشة:

4. عند الانتهاء من إضافة المَعلمات، انقر على "نشر التغييرات".
5. شغّل تطبيقك على محاكي أو جهاز مرة أخرى وانقر على "جلب الترحيب عن بُعد" هذه المرة.

6. يجب تعديل رسالة الترحيب بناءً على مَعلمة "الإعداد عن بُعد" وقيمها.

6- تهانينا

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

• بدء استخدام ميزة "الإعداد عن بُعد في Firebase"
• كيف يمكنني الاستفادة من ميزة "الإعداد عن بُعد"؟
• واجهة برمجة التطبيقات عن بُعد في Firebase
• إنشاء تجارب "الإعداد عن بُعد في Firebase" باستخدام ميزة "اختبار A/B"