المكوّن الإضافي Google Services Gradle الإضافي

مقدمة

كجزء من تفعيل واجهات Google API أو خدمات Firebase في تطبيق Android، قد تحتاج إلى إضافة المكوّن الإضافي google-services إلى ملف build.gradle:

dependencies {
    classpath 'com.google.gms:google-services:4.4.3'
    // ...
}

يتضمّن المكوّن الإضافي google-services وظيفتَين رئيسيتَين:

1. معالجة ملف google-services.json وإنشاء موارد Android يمكن استخدامها في رمز تطبيقك راجِع إضافة ملف JSON لمزيد من المعلومات.

2. أضِف التبعيات للمكتبات الأساسية المطلوبة للخدمات التي فعّلتها. تتطلّب هذه الخطوة تطبيق المكوّن الإضافي في "خدمات Google" لأداة Gradle في ملف app/build.gradle، كما يلي:
   apply plugin: 'com.google.gms.google-services'

   يمكنك الاطّلاع على نتيجة هذه الخطوة من خلال تنفيذ الأمر ./gradlew :app:dependencies.

إضافة ملف JSON

يتم وضع ملف google-services.json عادةً في الدليل app/ (في جذر وحدة تطبيق "استوديو Android"). بدءًا من الإصدار 2.2.0، تتيح الإضافة استخدام ملفات JSON خاصة بنوع الإصدار ونكهة المنتج. جميع بنى الدليل التالية صالحة:

// dogfood and release are build types.
app/
    google-services.json
    src/dogfood/google-services.json
    src/release/google-services.json
    ...

ملاحظة: يتيح توفير ملف google-services.json في دليل الإصدار لك الاحتفاظ بمشروع Firebase منفصل لحِزم APK الخاصة بالإنتاج.

عند استخدام نكهات المنتجات، تكون بنى الدليل الأكثر تعقيدًا هذه صالحة أيضًا.

// free and paid are product flavors.
app/
    google-services.json
    src/dogfood/paid/google-services.json
    src/release/free/google-services.json
    ...

معالجة ملف JSON

يتضمّن ملف google-services.json البنية الأساسية التالية:

{
  "project_info": {...},
  "client": [...],
}

يحتوي العنصر project_info على معلومات عامة حول مشروعك، بينما يحتوي كل عنصر من عناصر المصفوفة client على معلومات حول العملاء (تطبيقات Android) الذين أضفتهم إلى المشروع.

عند معالجة ملف JSON لتطبيق Android، لا تستخدم الإضافة سوى العنصر client الذي يتطابق مع اسم الحزمة (لنظام الإصدار الحالي) استنادًا إلى المنطق التالي:

• بالنسبة إلى كل عنصر من عناصر المصفوفة client:
  • تحقَّق من قيمة client_info/android_client_info/package_name
  • إذا تطابق اسم الحزمة مع هذه القيمة، اعرض عنصر العضو.
• إذا لم يتطابق أي من أعضاء client مع اسم الحزمة، سيتم عرض استثناء.

في بقية هذا المستند، سنستخدم {YOUR_CLIENT} للإشارة إلى عنصر مصفوفة client الذي تم تحديده باستخدام الإجراء المذكور أعلاه.

تتمثّل النتيجة الرئيسية لمعالجة JSON في إنشاء ملفَي XML يمكنك الرجوع إليهما كموارد Android في رمز Java البرمجي. في ما يلي مثال على كل ملف:

app/build/generated/res/google-services/{build_type}/values/values.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>

    <! -- Present in all applications -->
    <string name="google_app_id" translatable="false">1:1035469437089:android:73a4fb8297b2cd4f</string>

    <! -- Present in applications with the appropriate services configured -->
    <string name="gcm_defaultSenderId" translatable="false">1035469437089</string>
    <string name="default_web_client_id" translatable="false">337894902146-e4uksm38sne0bqrj6uvkbo4oiu4hvigl.apps.googleusercontent.com</string>
    <string name="ga_trackingId" translatable="false">UA-65557217-3</string>
    <string name="firebase_database_url" translatable="false">https://example-url.firebaseio.com</string>
    <string name="google_api_key" translatable="false">AIzbSyCILMsOuUKwN3qhtxrPq7FFemDJUAXTyZ8</string>
    <string name="google_crash_reporting_api_key" translatable="false">AIzbSyCILMsOuUKwN3qhtxrPq7FFemDJUAXTyZ8</string>
    <string name="project_id" translatable="false">mydemoapp</string>

</resources>

app/build/generated/res/google-services/{flavor}/{build_type}/xml/global_tracker.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="ga_trackingId" translatable="false">UA-65557218-3</string>
</resources>

تتوفّر كل قيمة في ملفات XML في ملف google-services.json في المواقع الجغرافية أدناه. إذا كان مشروع Android يتضمّن بعض الإعدادات التي تمنعك من استخدام المكوّن الإضافي google-services، يمكنك إعادة إنشاء ملفات XML يدويًا بأمان باستخدام القيم التالية:

google_app_id:

{YOUR_CLIENT}/client_info/mobilesdk_app_id

gcm_defaultSenderId:

project_info/project_number

default_web_client_id:

{YOUR_CLIENT}/oauth_client/client_id (client_type == 3)

ga_trackingId:

{YOUR_CLIENT}/services/analytics-service/analytics_property/tracking_id

firebase_database_url:

project_info/firebase_url

google_api_key:

{YOUR_CLIENT}/api_key/current_key

google_crash_reporting_api_key:

{YOUR_CLIENT}/api_key/current_key

project_id:

project_info/project_id

تحديد المشاكل وحلّها

س: عند إنشاء التطبيق، تظهر لي رسالة الخطأ التالية: "الملف google-services.json غير متوفّر في المجلد الجذر للوحدة. لا يمكن أن تعمل إضافة "خدمات Google" بدونها".

ج: ستساعدك وحدة تحكّم Firebase في تنزيل google-services.json. بالإضافة إلى ذلك، تتضمّن أدلة التشغيل السريع لمعظم واجهات برمجة التطبيقات تعليمات حول إنشاء هذا الملف. بعد تنزيل ملف google-services.json، انسخه إلى المجلد app/ في مشروع "استوديو Android" أو إلى المجلد app/src/{build_type} إذا كنت تستخدم أنواع إصدارات متعددة.

س: لا يمكنني العثور على الرمز "R.string.gcm_defaultSenderId" أو "R.xml.global_tracker" أو غير ذلك.

ج: تأكَّد من أنّ اسم الحزمة في ملف build.gradle يتطابق مع اسم الحزمة الذي أدخلته عند إنشاء ملف google-services.json. إذا لم تكن متأكدًا، عليك تنفيذ خطوات البدء مرة أخرى والحصول على ملف json جديد.