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

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

قبل البدء

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

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

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

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

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

تتكوّن حزمة App Distribution Android SDK من مكتبتَين:

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

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

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

    Java 

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

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

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

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

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

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

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

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

  2. تُجري عمليات تحقّق للتأكّد من أنّ المختبِر فعّل ميزات اختبار حِزم تطوير البرامج (SDK). إذا لم تكن ميزات الاختبار مفعّلة، تطلب حزمة تطوير البرامج (SDK) لنظام التشغيل Android من المختبِر تسجيل الدخول إلى App Distribution باستخدام حسابه على 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. أنشئ إصدارًا تجريبيًا من تطبيقك يتضمّن 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. اطّلِع على ملاحظاتك في بطاقة الإصدار الجديد في console 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. ثبِّت واجهة سطر أوامر Firebase وسجِّل الدخول إليها.

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

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

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

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