جمع الملاحظات من المختبِرين

يوضّح هذا الدليل كيفية تفعيل ميزة الملاحظات داخل التطبيق باستخدام حزمة تطوير البرامج (SDK) الاختيارية لـ Firebase App Distribution على Android، ليتمكّن المختبِرون من إرسال الملاحظات (بما في ذلك لقطات الشاشة) مباشرةً في التطبيق.

قبل البدء

أضِف Firebase إلى مشروع Android الخاص بك، في حال لم يسبق لك إجراء ذلك.

الخطوة 1: تفعيل واجهة برمجة التطبيقات App Distribution Tester API

  1. افتح وحدة تحكّم Google Cloud واختر مشروع Firebase.

  2. ضمن Firebase App Testers API، انقر على تفعيل.

الخطوة 2: إضافة App Distribution إلى تطبيقك

تتكوّن حزمة تطوير البرامج (SDK) لنظام التشغيل Android من App Distribution من مكتبتَين:

  • firebase-appdistribution-api: مكتبة واجهة برمجة التطبيقات فقط، والتي يمكنك تضمينها في جميع تنويعات التصميم.
  • ‫firebase-appdistribution: التنفيذ الكامل لحزمة تطوير البرامج (SDK) (اختياري)

تتيح المكتبة المخصّصة لواجهة برمجة التطبيقات فقط للرمز البرمجي إرسال طلبات إلى حزمة تطوير البرامج (SDK). ولن يكون لهذه الطلبات أي تأثير إذا لم يتم تنفيذ حزمة تطوير البرامج (SDK) بالكامل.

  1. حدِّد الاعتمادية لحزمة تطوير البرامج (SDK) الخاصة بـ App Distribution على Android في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle).

  2. لتجنُّب تضمين وظيفة التحديث الذاتي الكاملة لحزمة SDK في إصدارات Google Play، حدِّد تنويعات التصميم، بما في ذلك أنواع التصميم أو نكهات المنتج التي ستوزّعها من خلال App Distribution.

  3. حدِّد الاعتمادية لحزمة تطوير البرامج (SDK) الخاصة بـ App Distribution على Android في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً app/build.gradle). أضِف فقط عملية التنفيذ الكاملة لحزمة تطوير البرامج (SDK) إلى الصيغ المخصّصة حصريًا للاختبار التجريبي:

    Kotlin 

    dependencies {
    // ADD the API-only library to all variants
    implementation("com.google.firebase:firebase-appdistribution-api:16.0.0-beta21")

    // ADD the full SDK implementation to the "beta" variant only (example)
    betaImplementation("com.google.firebase:firebase-appdistribution:16.0.0-beta21")
}

    Java 

    dependencies {
    // ADD the API-only library to all variants
    implementation("com.google.firebase:firebase-appdistribution-api:16.0.0-beta21")

    // ADD the full SDK implementation to the "beta" variant only (example)
    betaImplementation("com.google.firebase:firebase-appdistribution:16.0.0-beta21")
}

هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ بدءًا من إصدار أكتوبر 2023، يمكن لمطوّري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية للحصول على التفاصيل، يُرجى الاطّلاع على الأسئلة الشائعة حول هذه المبادرة.

الخطوة 3: ضبط الملاحظات داخل التطبيق

لجمع الملاحظات من المختبِرين، استخدِم أحد الإجراءات التالية لتمكين المختبِرين من بدء تقديم الملاحظات:

  • مشغّل الإشعارات المضمّن: يمكن لحزمة تطوير البرامج (SDK) لنظام التشغيل Android في "App Distribution" عرض إشعار مستمر يمكن للمختبِر النقر عليه من أي مكان في التطبيق. يمكنك استخدام هذا المشغّل إذا أردت البدء بسرعة أكبر ولم تكن بحاجة إلى تخصيص طريقة تقديم المختبِرين للملاحظات.

  • عامل تشغيل مخصّص: يمكنك توفير آلية تشغيل خاصة بك، مثل النقر على زر أو عنصر قائمة في تطبيقك أو هزّ الجهاز.

عند استخدام أيّ من هذين المشغِّلَين وإرسال المختبِر للملاحظات، تنفِّذ حزمة تطوير البرامج (SDK) لنظام التشغيل Android الإجراءات التالية:

  1. يتم التقاط لقطة شاشة للنشاط الحالي للتطبيق.

  2. يتم إجراء عمليات تحقّق للتأكّد من أنّ المختبِر قد فعَّل ميزات الاختبار في حزمة تطوير البرامج (SDK). إذا لم تكن ميزات الاختبار مفعَّلة، ستطلب حزمة تطوير البرامج (SDK) لنظام التشغيل Android من المختبِر تسجيل الدخول إلى "App Distribution" باستخدام حسابه على Google.

  3. يبدأ هذا الإجراء نشاطًا بملء الشاشة يتيح للمختبِر كتابة ملاحظاته وإرسالها.

الخيار 1: عرض الإشعار

استخدِم showFeedbackNotification() لعرض إشعار دائم أو مستمر على جهاز المختبِر يمكنه النقر عليه لبدء تقديم الملاحظات. عند ضبط الإشعار، عليك تقديم بعض النصوص التي ستظهر للمختبِر قبل إرسال الملاحظات، ومستوى مقاطعة الإشعار (المقابل لأهمية قناة الإشعارات). إذا أردت إرسال إشعار إلى المختبِرين بشأن جمع بيانات ملاحظاتهم ومعالجتها، يمكنك استخدام النص لتقديم هذا الإشعار.

عند استخدام "showFeedbackNotification()" وعندما ينتقل التطبيق إلى الخلفية، يتم إخفاء الإشعار. إذا أردت إخفاء الإشعار بشكل صريح، استخدِم cancelFeedbackNotification(). ننصحك بوضع showFeedbackNotification() في onCreate() لنشاطك الرئيسي.

Kotlin 

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Firebase.appDistribution.showFeedbackNotification(
            // Text providing notice to your testers about collection and
            // processing of their feedback data
            R.string.additionalFormText,
            // The level of interruption for the notification
            InterruptionLevel.HIGH)
    }
}

Java 

public class MainActivity extends AppCompatActivity {
    FirebaseAppDistribution firebaseAppDistribution =
        FirebaseAppDistribution.getInstance();
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        firebaseAppDistribution.showFeedbackNotification(
            // Text providing notice to your testers about collection and
            // processing of their feedback data
            R.string.additionalFormText,
            // The level of interruption for the notification
            InterruptionLevel.HIGH);
    }
}

الخيار 2: عامل تشغيل مخصّص

استخدِم طريقة startFeedback() لبدء تقديم الملاحظات باستخدام آلية من اختيارك. على سبيل المثال، لتفعيل الملاحظات، يمكنك إضافة عنصر قائمة "إرسال ملاحظات" إلى قائمة الإجراءات في تطبيقك، أو السماح للمختبِرين بهزّ أجهزتهم أو أخذ لقطة شاشة. عند تفعيل الملاحظات، قدِّم بعض النصوص التي ستظهر للمختبِر قبل إرسال الملاحظات. إذا أردت تقديم إشعار للمختبِرين بشأن جمع بيانات ملاحظاتهم ومعالجتها، يمكنك استخدام هذا النص لتقديم هذا الإشعار.

Kotlin 

Firebase.appDistribution.startFeedback(R.string.feedbackMessage)

Java 

FirebaseAppDistribution.getInstance().startFeedback(R.string.feedbackMessage);

الخطوة 4: إنشاء عملية التنفيذ واختبارها

الاختبار المحلي

لاختبار عملية التنفيذ بدون الحاجة إلى توزيع التطبيق أولاً، اتّبِع الخطوات التالية:

  1. فعِّل وضع المطوّر على جهازك المحلي:

    adb shell setprop debug.firebase.appdistro.devmode true

  2. أنشئ تطبيقك كإصدار تجريبي يتضمّن مكتبات App Distribution الكاملة، واختبِر إمكانية تفعيل الملاحظات باستخدام الآلية المطبَّقة في الخطوة 3: ضبط الملاحظات داخل التطبيق. لا يتم إرسال الملاحظات في وضع المطوّر.

  3. بعد الاختبار، يمكنك إيقاف وضع المطوّر على جهازك:

    adb shell setprop debug.firebase.appdistro.devmode false

الاختبار الشامل

لاختبار قدرة تطبيقك على إرسال الملاحظات، يمكنك إنشاء تطبيقك كإصدار تجريبي يتضمّن مكتبات App Distribution الكاملة، واختبار عملية التنفيذ باتّباع الخطوات التالية:

  1. حمِّل إصدار تطبيق جديدًا إلى App Distribution.

  2. توزيع إصدار التطبيق على حساب لديك إذن بالوصول إليه

  3. نزِّل التطبيق من خلال تطبيق المختبِر على الويب أو على Android من "App Distribution".

  4. يمكنك تفعيل الملاحظات باستخدام الآلية المطبَّقة في الخطوة 3: ضبط الملاحظات داخل التطبيق.

  5. تأكَّد من تسجيل الدخول باستخدام الحساب نفسه الذي وزّعت من خلاله إصدار التطبيق، ثم أرسِل الملاحظات.

  6. يمكنك الاطّلاع على ملاحظاتك في بطاقة الإصدار الجديد في وحدة تحكّم Firebase.

لمعرفة كيفية حلّ المشاكل الشائعة، مثل عدم تمكُّن المختبِرين من بدء تقديم الملاحظات في التطبيق، يُرجى الاطّلاع على مقالة تفعيل ميزات الاختبار باستخدام حزمة تطوير البرامج (SDK).

الخطوة 5: إدارة ملاحظات المختبِرين

بعد تفعيل ميزة إرسال الملاحظات للمختبِرين، يمكنك استخدام الأدوات التالية لمراجعة هذه الملاحظات واتّخاذ الإجراءات اللازمة بشأنها:

عرض الملاحظات وحذفها في وحدة تحكّم "Firebase"

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

بعد مراجعة ملاحظات المستخدمين، يمكنك حذفها بالنقر على الزر حذف الملاحظات. تتم إزالة الملاحظات المحذوفة من الإصدار.

تلقّي تنبيهات عبر البريد الإلكتروني بشأن الملاحظات الجديدة

للاطّلاع بشكل استباقي على الملاحظات الجديدة من المختبِرين، يمكنك تلقّي تنبيهات عبر البريد الإلكتروني عندما يرسل أحد المختبِرين ملاحظاته. يتضمن التنبيه عبر البريد الإلكتروني الملاحظات المكتوبة التي قدمها المختبِر ورابطًا لأي لقطات شاشة أرسلها.

لتلقّي تنبيهات عبر البريد الإلكتروني من "App Distribution" باستخدام هذه الآلية التلقائية، يجب أن يكون لديك إذن "firebase.projects.update". تتضمّن الأدوار التالية هذا الإذن المطلوب تلقائيًا: مشرف Firebase أو مالك المشروع أو محرِّره.

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

لإيقاف التنبيهات عبر البريد الإلكتروني، يُرجى الاطّلاع على تلقّي تنبيهات Firebase.

إرسال ملاحظات جديدة إلى الأدوات الخارجية

يمكنك أيضًا إرسال تنبيهات App Distribution إلى قناة الإشعارات المفضّلة لدى فريقك باستخدام Cloud Functions for Firebase. على سبيل المثال، يمكنك كتابة دالة تلتقط حدث تنبيه للملاحظات الجديدة داخل التطبيق وتنشر معلومات التنبيه إلى خدمة تابعة لجهة خارجية مثل Discord أو Slack أو Jira.

لإعداد ميزات التنبيهات المتقدّمة باستخدام Cloud Functions for Firebase، يُرجى اتّباع الخطوات التالية:

  1. إعداد Cloud Functions for Firebase، والذي يتضمّن المهام التالية:

    1. نزِّل Node.js وnpm.

    2. ثبِّت واجهة سطر الأوامر (CLI) في Firebase وسجِّل الدخول إليها.

    3. ابدأ إعداد Cloud Functions for Firebase باستخدام واجهة سطر الأوامر (CLI) في Firebase.

  2. اكتب دالة وانشرها لالتقاط حدث تنبيه بشأن الملاحظات داخل التطبيق من App Distribution ومعالجة حمولة الحدث (على سبيل المثال، نشر معلومات التنبيه في رسالة على Discord).

للاطّلاع على مثال على دالة توضّح كيفية إرسال ملاحظات جديدة إلى Jira، يُرجى الرجوع إلى نموذج الدوال هذا.

للتعرّف على جميع أحداث التنبيهات التي يمكنك تسجيلها، يُرجى الاطّلاع على المستندات المرجعية حول تنبيهات App Distribution.