افزونه Gradle سرویس‌های Google و فایل پیکربندی JSON

به‌عنوان بخشی از افزودن Firebase به پروژه Android، باید افزایه Gradle google-services و فایل پیکربندی google-services.json را به پروژه‌تان اضافه کنید.

اگر Firebase را بااستفاده از کنسول Firebase، Management REST API، یا Firebase CLI به پروژه Android خود اضافه کنید، باید افزونه Gradle و فایل پیکربندی JSON را به‌صورت دستی به پروژه خود اضافه کنید. اما اگر از Firebase Assistant for Android Studio استفاده کنید، این کارها به‌طور خودکار درطول راه‌اندازی برایتان انجام می‌شود.

افزودن افزایه Gradle

افزایه Gradle سرویس‌های Google (google-services) را به فایل build.gradle خود اضافه می‌کنید:

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

افزایه Gradle خدمات Google دو عملکرد اصلی دارد:

  • فایل پیکربندی google-services.json را پردازش می‌کند و منابع Android را که می‌توانند در کد برنامه‌تان استفاده شوند تولید می‌کند.

  • وابستگی‌های کتابخانه‌های پایه موردنیاز برای سرویس‌هایی را که فعال کرده‌اید اضافه می‌کند. این مرحله مستلزم این است که افزایه Gradle سرویس‌های Google را در فایل 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
    ...

وقتی از نسخه‌های ویژه محصول استفاده می‌شود، این ساختارهای پیچیده‌تر دایرکتوری نیز معتبر هستند.

// 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 که با منطق شرح‌داده‌شده در بالا تعیین شده است استفاده می‌شود.

تولید فایل‌های XML

نتیجه اصلی پردازش JSON تولید دو فایل XML است که می‌توانید به‌عنوان منابع Android در کدتان به آن‌ها ارجاع دهید. در زیر نمونه‌هایی از هریک از این فایل‌ها آورده شده است:

  • 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

هر مقدار در فایل‌های XML در فایل پیکربندی google-services.json در مکان‌های فهرست‌شده در زیر وجود دارد. اگر پروژه Android شما پیکربندی‌ای دارد که مانع از استفاده شما از افزونه google-services Gradle می‌شود، می‌توانید بااستفاده از این مقادیر، فایل‌های 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

عیب‌یابی

هنگام ساختن، این پیام خطا را دریافت می‌کنم: File google-services.json is missing from module root folder. The Google Services Plugin cannot function without it.

کنسول 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 جدیدی دریافت کنید.