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

يوضّح هذا الدليل كيفية تفعيل ميزة "الملاحظات داخل التطبيق" باستخدام حزمة تطوير البرامج (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). لن يكون للطلبات أي تأثير إذا لم تكن عملية التنفيذ الكاملة لحزمة تطوير البرامج (SDK) متوفّرة.

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

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

  3. حدِّد الاعتمادية لحزمة تطوير البرامج (SDK) لنظام التشغيل Android الخاصة بخدمة App Distribution في ملف 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-beta20")

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

    Java 

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

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

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

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

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

  • مشغّل الإشعارات المضمّن: يمكن لحزمة تطوير البرامج (SDK) لنظام التشغيل AndroidApp 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 Console.

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

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

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

عرض الملاحظات وحذفها في Firebase Console

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

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

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

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

لتلقّي تنبيهات عبر البريد الإلكتروني من خلال هذه الآلية التلقائية، يجب أن يكون لديك إذن firebase.projects.updateApp Distribution تتضمّن الأدوار التالية هذا الإذن المطلوب بشكلٍ تلقائي: مشرف 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 CLI وتسجيل الدخول إليه

    3. تهيئة Cloud Functions for Firebase باستخدام Firebase CLI.

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

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

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