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

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

قبل البدء

أضِف 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 بالكامل.

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

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

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

    Kotlin 

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

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

    Java 

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

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

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

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

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

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

عند استخدام أي من المشغِّلَين وإرسال المختبِر ملاحظات، تنفِّذ حزمة تطوير البرامج (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. نزِّل التطبيق من خلال موقع App Distribution الإلكتروني أو تطبيق اختبار Android.

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

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

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

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

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

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

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

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

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

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

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

لتلقّي تنبيهات عبر البريد الإلكتروني بشأن 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. ثبِّت واجهة سطر الأوامر Firebase وسجِّل الدخول إليها.

    3. ابدأ Cloud Functions for Firebase باستخدام واجهة سطر الأوامر Firebase.

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

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

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