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

1. مقدمة

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

ما هو الإعداد عن بُعد عبر Firebase؟

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

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

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

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

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

61f12f33d2ac3133.png

ما ستتعلمه

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

المتطلبات

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

2. إعداد حساب

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

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

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

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

...أو استنسِخ مستودع GitHub من سطر الأوامر.

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

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

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

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

5f90353b0b519642.png

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

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

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

إنشاء مشروع Firebase

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

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

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

  1. (اختياري) إذا كنت بصدد إنشاء مشروع جديد، يمكنك تعديل رقم تعريف المشروع.

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

  1. انقر على متابعة.
  2. يمكنك إعداد "إحصاءات Google" لمشروعك، ما يتيح لك الحصول على أفضل تجربة باستخدام أيّ من منتجات Firebase التالية:
  • Firebase Crashlytics
  • توقعات Firebase
  • المراسلة عبر السحابة الإلكترونية من Firebase
  • المراسلة داخل تطبيق Firebase
  • الإعداد عن بُعد في Firebase
  • اختبار A/B من Firebase

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

1282a798556779ab.png

48ade68c8de27d2.png

  1. انقر على إنشاء مشروع (أو إضافة 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 على Firebase (google-services.json).

bc8ec7d3c9a28d75.png

a99b7415462dfc8b.png

في ملف Gradle على مستوى المشروع (build.gradle)، أضِف قواعد لتضمين المكوّن الإضافي Google Services Gradle. تأكَّد أيضًا من توفُّر مستودع 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):

apply plugin: ‘com.android.application'

// أضِف السطر التالي:

apply plugin: ‘com.google.gms.google-services' // Google Services plugin

android {

‪// ...

}

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

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

(يتم ذلك تلقائيًا في نموذج رمز التشغيل السريع)

باستخدام قائمة مواد منصة Firebase لأجهزة Android، حدِّد الاعتمادية لمكتبة "الإعداد عن بُعد" على نظام التشغيل Android في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً app/build.gradle). وباستخدام قائمة مواد منصة Firebase لأجهزة Android، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات 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);

يتم استخدام عنصر singleton لتخزين قيم المَعلمات التلقائية داخل التطبيق، واسترداد قيم المَعلمات المعدَّلة من الخلفية، والتحكّم في الوقت الذي تصبح فيه القيم المستردّة متاحة لتطبيقك.

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

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

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

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

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

4b8a2a637a626e94.png

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

358b4ba740120ece.png

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

MainActivity.java

mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

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

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

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

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

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

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

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

إذا كان التطبيق يجلب البيانات عدة مرات خلال فترة زمنية قصيرة، يتم تقييد عدد مرات جلب البيانات وتعرض حزمة 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).

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.

c1582b989c25ced.png

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

4c838bf5a629d5b8.png

تحديد قيم المَعلمات في خلفية "الإعداد عن بُعد"

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

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

مفتاح المَعلمة

القيمة التلقائية (remote_config_defaults.xml)

الوصف

loading_phrase

جارٍ جلب الإعداد...

سلسلة، يتم عرضها عند جلب قيم "الإعداد عن بُعد".

welcome_message_caps

خطأ

قيمة منطقية. إذا كانت القيمة true، سيتم تغيير welcome_message إلى أحرف كبيرة

welcome_message

مرحبًا بك في تطبيقي الرائع!

سلسلة؛ رسالة الترحيب

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

28fa48f18da43002.png

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

cfe900477549adb7.png

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

6. تهانينا

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