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

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

قبل البدء

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

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

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

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

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

تتألف حزمة تطوير برامج Android لتوزيع التطبيقات من مكتبتَين:

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

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

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

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

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

    Kotlin+KTX 

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

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

    Java 

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

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

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

لجمع الملاحظات من المختبِرين، استخدِم أحد عاملَي التفعيل التاليَين للسماح للمختبِرين ببدء تقديم ملاحظاتهم:

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

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

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

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

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

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

الخيار 1: مشغِّل الإشعار

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

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

Kotlin+KTX 

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+KTX 

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

Java 

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

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

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

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

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

    adb shell setprop debug.firebase.appdistro.devmode true

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

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

    adb shell setprop debug.firebase.appdistro.devmode false

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

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

  1. حمِّل إصدار تطبيق جديدًا إلى ميزة "توزيع التطبيقات".

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

  3. يمكنك تنزيل التطبيق من خلال الويب أو التطبيق المخصّص لاختبار Android من App Distribution.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لإعداد إمكانات التنبيه المتقدمة باستخدام وظائف السحابة الإلكترونية لبرنامج Firebase، اتّبِع الخطوات التالية:

  1. إعداد دوال السحابة الإلكترونية لبرنامج Firebase، الذي يتضمن المهام التالية:

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

    2. ثبِّت واجهة سطر الأوامر لمنصّة Firebase وسجِّل الدخول إليها.

    3. إعداد وظائف السحابة الإلكترونية لبرنامج Firebase باستخدام واجهة سطر الأوامر في Firebase

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

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

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