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

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

قبل البدء

أضِف 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: ضبط ميزة "ملاحظات المستخدمين" داخل التطبيق

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

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

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

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