تغييرات معرف الإعلانات: كيف يتم جلب معرف إعلانات جوجل (GAID) في نظام Android 13 والأحدث؟

ما هو معرف GAID وكيف يتم جلبه برمجياً؟ معرف إعلانات جوجل (GAID) هو معرف برمجي يمكن للمستخدم إعادة تعيينه، توفره خدمات Google Play لقياس الأداء الإعلاني. يتم استرجاعه برمجياً خارج الخيط الرئيسي (Main Thread) باستخدام واجهة برمجة التطبيقات AdvertisingIdClient، وذلك بعد التأكد من أن ملف البيان (Manifest) المُدمج للتطبيق يتضمن إذن AD_ID عند الحاجة.

يُعرف معرف إعلانات جوجل (GAID) أيضاً باسم معرف إعلانات أندرويد (AAID)، وهو عبارة عن سلسلة فريدة يمكن للمستخدم إعادة تعيينها، توفرها خدمات Google Play بغرض قياس نسب الإحالة الإعلانية، والاستهداف الإعلاني المُخصص، وتحليلات البيانات على أجهزة أندرويد. يجب على التطبيقات التي تستهدف نظام Android 13 (مستوى واجهة برمجة التطبيقات API 33) أو الإصدارات الأحدث التأكد من أن ملف البيان المُدمج يحتوي على إذن com.google.android.gms.permission.AD_ID عند محاولة الوصول إلى معرف إعلانات خدمات Google Play، وإلا فإن واجهة برمجة التطبيقات ستعيد قيمة صفرية بالكامل.

ما هو معرف GAID وكيف تعمل آليات معرف إعلانات جوجل

التشريح التقني لمعرف الإعلانات

يتم إرجاع معرف إعلانات جوجل (GAID) بواسطة خدمات Google Play في صورة سلسلة معرف مُبهمة، وعادةً ما يتم تنسيقها كمعرف فريد عالمياً (UUID) ست عشري مكون من 128 بتاً بأحرف صغيرة (مثل: 38400000-8cf0-11bd-b23e-10b96e4ef00d). ينبغي على التطبيقات التعامل مع السلسلة المُسترجعة كمعرف مُبهم بدلاً من استنتاج منطق الأعمال من تنسيقه.

على عكس المعرفات على مستوى الأجهزة، تم تصميم معرف GAID مع تفعيل ضوابط خصوصية صريحة:

• قابل لإعادة التعيين من قِبل المستخدم: يمكن للمستخدمين إنشاء معرف عشوائي جديد في أي وقت عبر إعدادات الجهاز.
• قابل للحذف من قِبل المستخدم: بدءاً من نظام Android 12، يمكن للمستخدمين حذف معرف الإعلانات الخاص بهم، مما يوجه خدمات Google Play لحجب معرفات الإعلانات عن جميع التطبيقات.
• نطاق الجهاز لكل ملف تعريف: تتوافر معرفات الإعلانات عموماً عبر التطبيقات لنفس ملف تعريف المستخدم على الجهاز، ولكن تتلقى ملفات تعريف المستخدمين أو الضيوف المختلفة على نفس الجهاز الفعلي معرفات إعلانية متميزة.

دور خدمات Google Play في إدارة حالة المعرف

لا يُعد معرف GAID جزءاً من إطار عمل أندرويد الأساسي مفتوح المصدر؛ بل هو خدمة على مستوى التطبيق تتم إدارتها وتقديمها ديناميكياً بواسطة مكتبة عميل خدمات Google Play المُغلقة (com.google.android.gms:play-services-ads-identifier).

عندما يقوم أي تطبيق باستدعاء خدمات Google Play، يقوم العميل بإجراء اتصال حظري مع خدمات Google Play لاسترداد معرف الإعلانات الحالي وتفضيلات المستخدم المتعلقة بالحد من تتبع الإعلانات.

لماذا استبدل معرف GAID معرفات الأجهزة؟

في إصدارات أندرويد المبكرة، كانت شبكات الإعلانات والمطورون يتتبعون أحداث التحويل باستخدام معرفات أجهزة لا يمكن إعادة تعيينها:

• معرف الأجهزة المحمولة الدولية (IMEI): مرتبط بمكونات الأجهزة الخلوية للجهاز.
• عنوان التحكم في الوصول للوسط (MAC Address): مرتبط بمكونات واجهة شبكة الاتصال.
• ANDROID_ID (SSAID): في إصدارات أندرويد الحديثة 8.0+، يتم تحديد نطاق هذا المعرف لكل مجموعة من مفتاح توقيع التطبيق، والمستخدم، والجهاز بدلاً من عمله كمعرف إعلاني عام عبر التطبيقات.

لحالات الاستخدام الإعلاني على Google Play، يجب على المطورين استخدام معرف الإعلانات عندما يكون متاحاً بدلاً من استبداله بمعرف جهاز دائم آخر.

انظر أيضاً: معرف GAID ──> هيكلية الإحالة للأجهزة المحمولة

متطلبات أذونات Android 13: التصريح بملف البيان AD_ID

نموذج فرض مستوى واجهة برمجة التطبيقات 33

بدءاً من نظام Android 13 (مستوى واجهة برمجة التطبيقات 33)، قدمت جوجل إذن com.google.android.gms.permission.AD_ID:

• حزمة SDK المستهدفة 33 والأحدث: يجب على التطبيقات التي تستهدف نظام Android 13 أو الأحدث التصريح بإذن AD_ID في ملف البيان الخاص بها. وفي حال تم إغفال هذا الإذن، تُرجع خدمات Google Play سلسلة من الأصفار (00000000-0000-0000-0000-000000000000).
• حزمة SDK المستهدفة 32 والأقدم: لا يكون إذن AD_ID مطلوباً في ملف البيان. ومع ذلك، قد يظل معرف الإعلانات غير متاح أو صفرياً بسبب إعدادات خصوصية معرف الإعلانات الخاصة بالمستخدم، بما في ذلك حالات الحد من تتبع الإعلانات أو الحذف.
• إعلانات سياسة متجر التطبيقات: عند إرسال تحديث يستهدف مستوى واجهة برمجة التطبيقات 33+، يجب على المطورين إكمال الإقرار الحالي لمعرف الإعلانات في وحدة تحكم Google Play (Google Play Console)، مع الإبلاغ بدقة عما إذا كان التطبيق يستخدم المعرف وكيفية استخدامه.

تكوين ملف AndroidManifest.xml وتبعيات Gradle

للتصريح بالإذن، قم بتضمين وسم <uses-permission> داخل ملف AndroidManifest.xml. وفي ملف build.gradle الخاص بوحدة التطبيق، أضف تبعية play-services-ads-identifier الرسمية.

يوضح التكوين أدناه بناء جملة إذن البيان وإعداد تبعية Gradle:

```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp">

    <!-- مطلوب على API 33+ للوصول إلى معرف GAID غير الصفري -->
    <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

    <application
        android:allowBackup="true"
        android:label="@string/app_name"
        android:theme="@style/Theme.MyApp">
        <!-- مكونات التطبيق -->
    </application>
</manifest>

// الموقع: app/build.gradle
// ملاحظة: إصدارات التبعية المعروضة هي أمثلة؛ يرجى التحقق من الإصدارات المستقرة الحالية في المستودعات الرسمية قبل الاستخدام في الإنتاج.

dependencies {
    // مكتبة معرف إعلانات خدمات Google Play الرسمية
    implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'

    // استخدام Kotlin Coroutines للتنفيذ الغير متزامن خارج الخيط الرئيسي
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
}

فهم دمج ملفات البيان: حقن حزم SDK العابرة

عند بناء حزمة APK أو حزمة تطبيقات أندرويد (AAB)، يقوم نظام بناء Gradle بدمج ملفات البيان من جميع مكتبات الطرف الثالث المُستوردة في ملف AndroidManifest.xml نهائي واحد.

إذا قامت أي حزمة SDK لشبكة إعلانية مُستوردة، أو أداة تحليلات، أو مكتبة إحالة بالتصريح عن com.google.android.gms.permission.AD_ID في ملف البيان الداخلي الخاص بها، فسيتم دمج هذا الإذن تلقائياً في نسختك النهائية. يمكن للمطورين فحص ملف app/build/outputs/logs/manifest-merger-release-report.txt لمراجعة التبعية التي قامت بإدراج هذا الإذن.

الاسترجاع البرمجي: جلب معرف GAID عبر AdvertisingIdClient في لغة Kotlin

قاعدة التنفيذ الإلزامي خارج الخيط الرئيسي

يؤدي استدعاء الدالة AdvertisingIdClient.getAdvertisingIdInfo(context) إلى بدء اتصال متزامن مع خدمات Google Play. وتمنع جوجل صراحةً تنفيذ هذه الطريقة على الخيط الرئيسي (واجهة المستخدم).

يتسبب استدعاء getAdvertisingIdInfo() على الخيط الرئيسي في إطلاق استثناء فوري من نوع IllegalStateException:

java.lang.IllegalStateException: Calling this from your main thread can lead to deadlock

لمنع أخطاء عدم استجابة التطبيق (ANR) وأعطال وقت التشغيل، يجب على المطورين توجيه عملية الاستخراج داخل عامل خلفي (Background Worker) أو باستخدام Kotlin Coroutine مع Dispatchers.IO.

تنفيذ مهام العامل الخلفي باستخدام Kotlin Coroutines

يوضح تطبيق لغة Kotlin أدناه نظام AdvertisingIdManager الآمن للتعامل مع الخيوط، والذي يقوم بتنفيذ الاستخراج خارج الخيط الرئيسي، ويتعامل مع استثناءات توفر خدمات Google Play، ويتحقق من سلامة المعرف:

package com.example.myapp.analytics

import android.content.Context
import android.util.Log
import com.google.android.gms.ads.identifier.AdvertisingIdClient
import com.google.android.gms.common.GooglePlayServicesNotAvailableException
import com.google.android.gms.common.GooglePlayServicesRepairableException
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import java.io.IOException

data class GaidResult(
    val gaid: String?,
    val isLimitAdTrackingEnabled: Boolean,
    val isZeroed: Boolean,
    val isAvailable: Boolean
)

object AdvertisingIdManager {

    private const val TAG = "AdvertisingIdManager"
    private const val ZEROED_GAID = "00000000-0000-0000-0000-000000000000"

    /**
     * استرداد معرف إعلانات جوجل برمجياً خارج خيط التنفيذ الرئيسي.
     * يتعامل تلقائياً مع الاستثناءات، والحالات الصفرية، وخيارات إلغاء الاشتراك الخاصة بالمستخدم.
     */
    suspend fun fetchGaid(context: Context): GaidResult = withContext(Dispatchers.IO) {
        try {
            // استدعاء اتصال IPC الحظري لخدمات Google Play على موزع مهام IO Coroutine
            val adInfo: AdvertisingIdClient.Info = AdvertisingIdClient.getAdvertisingIdInfo(context)
            
            val rawId = adInfo.id
            val isLAT = adInfo.isLimitAdTrackingEnabled
            val isZeroed = rawId == null || rawId.equals(ZEROED_GAID, ignoreCase = true)

            if (isZeroed) {
                Log.w(TAG, "معرف الإعلانات غير متوفر أو صفري.")
                GaidResult(
                    gaid = null,
                    isLimitAdTrackingEnabled = isLAT,
                    isZeroed = true,
                    isAvailable = false
                )
            } else {
                Log.d(TAG, "تم استرداد معرف الإعلانات بنجاح. تفعيل الحد من التتبع: $isLAT")
                GaidResult(
                    gaid = rawId,
                    isLimitAdTrackingEnabled = isLAT,
                    isZeroed = false,
                    isAvailable = true
                )
            }
        } catch (e: GooglePlayServicesNotAvailableException) {
            Log.e(TAG, "خدمات Google Play غير مثبتة أو غير متوفرة على هذا الجهاز.", e)
            GaidResult(gaid = null, isLimitAdTrackingEnabled = true, isZeroed = false, isAvailable = false)
        } catch (e: GooglePlayServicesRepairableException) {
            Log.w(TAG, "خدمات Google Play تتطلب تحديثاً أو تدخلاً من المستخدم.", e)
            GaidResult(gaid = null, isLimitAdTrackingEnabled = true, isZeroed = false, isAvailable = false)
        } catch (e: IOException) {
            Log.e(TAG, "خطأ في الاتصال أثناء ربط خدمات Google Play.", e)
            GaidResult(gaid = null, isLimitAdTrackingEnabled = true, isZeroed = false, isAvailable = false)
        } catch (e: IllegalStateException) {
            Log.e(TAG, "حالة غير صالحة أثناء استرداد معرف الإعلانات.", e)
            GaidResult(gaid = null, isLimitAdTrackingEnabled = true, isZeroed = false, isAvailable = false)
        } catch (e: Exception) {
            Log.e(TAG, "خطأ غير متوقع أثناء استرداد معرف إعلانات جوجل.", e)
            GaidResult(gaid = null, isLimitAdTrackingEnabled = true, isZeroed = false, isAvailable = false)
        }
    }
}

تحليل كائن AdvertisingIdClient.Info والتعامل مع خاصية الحد من تتبع الإعلانات

ترجع دالة AdvertisingIdClient.getAdvertisingIdInfo() كئناً من نوع AdvertisingIdClient.Info يحتوي على خاصيتين أساسيتين:

• getId() (String): السلسلة النصية الأبجدية الرقمية التي تمثل معرف الإعلانات.
• isLimitAdTrackingEnabled() (Boolean): عند تمكين ميزة الحد من تتبع الإعلانات، تحظر سياسة Google Play استخدام بيانات معرف الإعلانات لإنشاء ملفات تعريف إعلانية أو استهداف الإعلانات المُخصصة. ومع ذلك، تسمح السياسة بأنشطة مثل الإعلانات السياقية، وتحديد سقف مرات الظهور، وتتبع التحويلات، والتقارير، والكشف عن الأمان والاحتيال؛ ولكن في إصدارات خدمات Google Play الحالية، يتم تصفير معرف الإعلانات نفسه عند تمكين هذا الإعداد، لذا يجب على التطبيقات عدم افتراض بقاء معرف GAID صالح للاستخدام ومتاحاً.

التعامل مع المعرفات الصفرية وحالات الحذف المُبادرة من قِبل المستخدم

سلسلة 00000000-0000-0000-0000-000000000000: متى ولماذا تظهر

في بيئات الإنتاج، تُرجع دالة AdvertisingIdClient.Info.getId() القيمة 00000000-0000-0000-0000-000000000000 في الحالات التالية:

1. حذف المستخدم لمعرف الإعلانات: انتقل المستخدم إلى إعدادات الجهاز وقام بحذف معرف الإعلانات الخاص به.
2. تمكين الحد من تتبع الإعلانات: قام المستخدم بتفعيل الحد من تتبع الإعلانات على إصدارات نظام التشغيل المدعومة.
3. فقدان إذن ملف البيان: يستهدف التطبيق نظام Android 13+ (مستوى واجهة برمجة التطبيقات 33+) وفشل في التصريح بإذن com.google.android.gms.permission.AD_ID في ملف البيان المُدمج الخاص به.

سير عمل إعدادات المستخدم: حذف معرف الإعلانات

يمكن للمستخدمين على إصدارات أندرويد الحالية إزالة معرفهم عبر الانتقال إلى:

الإعدادات > الخصوصية > الإعلانات > حذف معرف الإعلانات (قد تختلف التسميات الدقيقة باختلاف الشركات المصنعة للأجهزة).

عند الحذف، تقوم خدمات Google Play بمسح القيمة الأساسية، وتُرجع طلبات واجهة برمجة التطبيقات اللاحقة عبر جميع التطبيقات المثبتة السلسلة الصفرية.

متطلبات سياسة Google Play لإعادة التعيين وحالات الحذف

وفقاً لـ سياسات مطوري Google Play بشأن معرف الإعلانات، يجب على المطورين التعامل مع إجراءات خصوصية المستخدم وفقاً لقواعد صريحة:

• متطلبات إعادة التعيين: عندما يقوم المستخدم بإعادة تعيين معرف الإعلانات الخاص به، يجب ألا يقوم المطورون بربط أو توصيل معرف الإعلانات الجديد بمعرف إعلانات سابق أو ببيانات مستمدة منه دون موافقة صريحة من المستخدم.
• متطلبات الحذف: عندما يحذف المستخدم معرف الإعلانات الخاص به، يجب ألا يقوم المطورون بربط ذلك الجهاز بالبيانات المرتبطة بمعرف الإعلانات السابق أو المستمدة منه.

تنقية مُدخلات المعرف في خطوط استيعاب البيانات الخلفية

يجب على أنظمة الإحالة الخلفية تطبيق مرشحات التحقق لمنع السلسلة الصفرية من تلويث قواعد بيانات الإحالة:

fun isGaidValid(gaid: String?): Boolean {
    if (gaid.isNullOrBlank()) return false
    val zeroedGaid = "00000000-0000-0000-0000-000000000000"
    return !gaid.equals(zeroedGaid, ignoreCase = true)
}

في حال اكتشاف معرف صفري، يجب ألا تتعامل الأنظمة اللاحقة معه كمعرف GAID قابل للاستخدام أو كمفتاح مطابقة للمعرف؛ وينبغي لأي معالجة للإحالة أو التحليلات الاعتماد فقط على الإشارات الأخرى المسموح بها بشكل مستقل.

سياسة العائلات في Google Play القيود المفروضة على فئات التطبيقات

ممارسات البيانات في تطبيقات برنامج العائلات

يفرض متجر Google Play قواعد صارمة لحماية البيانات بالنسبة للتطبيقات المشاركة في برنامج العائلات (Families) أو التي تستهدف الأطفال:

• حظر نقل معرف AAID: يجب ألا تقوم التطبيقات التي تستهدف الأطفال حصرياً بنقل معرف الإعلانات (AAID). بالنسبة للتطبيقات التي تستهدف مستوى واجهة برمجة التطبيقات 33 أو الأحدث، توفر جوجل توصية بإغفال أو تعطيل إذن AD_ID كآلية امتثال مباشرة.
• التعامل مع الجمهور المختلط: يجب ألا تقوم التطبيقات التي تستهدف الأطفال والجمهور الأكبر سناً معاً بنقل معرف AAID من الأطفال أو المستخدمين الذين تكون أعمارهم مجهولة. بشكل افتراضي، يجب على التطبيقات وحزم SDK تجنب نقل معرف AAID إلى أن يؤكد التحقق من العمر أن المستخدم ليس طفلاً.

استخدام الأدوات: node=“remove” في ملف البيان

إذا كان تطبيقك يستهدف الأطفال، ولكن حزمة SDK تابعة لجهة خارجية مُستوردة تقوم تلقائياً بحقن إذن AD_ID عبر ميزة دمج ملفات البيان، فيمكنك إضافة السمة tools:node="remove" داخل ملف AndroidManifest.xml الرئيسي الخاص بك:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.example.familyapp">

    <!-- إزالة إذن AD_ID المحقون بواسطة التبعيات العابرة صراحةً -->
    <uses-permission 
        android:name="com.google.android.gms.permission.AD_ID" 
        tools:node="remove"/>

</manifest>

بدائل القياس المخصصة لحالات الاستخدام عندما يكون معرف GAID غير متوفر

عندما يكون معرف GAID صفرياً، أو محذوفاً، أو مقيداً بالسياسة، تلجأ فرق الهندسة إلى بدائل مخصصة لحالات الاستخدام استناداً إلى هدفها الوظيفي:

• إحالة الحملات الإعلانية: استخدم واجهة برمجة تطبيقات إحالة تثبيت Google Play Install Referrer API لاسترداد بارامترات الحملات التي يتم الوساطة فيها عبر المتجر والتي تمر عبر عنوان URL الخاص بمتجر Play (أي referrer=...). وتعمل بشكل مستقل عن حذف معرف GAID.
• التسجيل (Onboarding) ونية المستخدم: استخدم توجيه البارامترات السياقية الخاصة بالطرف الأول لاستعادة رموز الإحالة، والرموز الترويجية، ووجهات الروابط العميقة التي يتم تمريرها من صفحات الهبوط على الويب.
• التحليلات المخصصة للمطورين واكتشاف الاحتيال: استخدم معرف مجموعة التطبيقات (AppSetIdClient) لإنشاء معرف مشترك عبر التطبيقات المنشورة تحت نفس حساب المطور، وذلك دون تتبع الإعلانات عبر التطبيقات.

                    معرف GAID غير متوفر أو صفري
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
         ▼                       ▼                       ▼
   إحالة الحملات المدفوعة     التسجيل ونية            التحليلات واكتشاف
                            الإحالة                    الاحتيال الخاصة بالمطور
         │                       │                       │
         ▼                       ▼                       ▼
    Google Play             البارامترات السياقية       معرف مجموعة التطبيقات App Set ID
  Install Referrer          للطرف الأول             (نطاق المطور أو التطبيق)
     (رابط المتجر)

المصفوفة المقارنة: معرف GAID مقابل Install Referrer مقابل App Set ID

الملخص وإطار اتخاذ القرار

يظل معرف إعلانات جوجل معرّفاً أساسياً قابلاً لإعادة التعيين لحالات استخدام الإعلانات وتحليلات المستخدمين في أندرويد، ولكن العمل على نظام Android 13+ يتطلب الالتزام بسياسات أذونات ملف البيان، ومعايير التنفيذ في الخلفية، والتعامل السلس مع حالات المعرف الصفري. وعندما يكون معرف GAID غير متوفر، يجب على الفرق الهندسية اختيار نموذج قياس استناداً إلى حالة الاستخدام المحددة—على سبيل المثال، استخدام Install Referrer لإحالة حملات متجر Play، أو البارامترات السياقية للطرف الأول لحالة التسجيل، أو معرف مجموعة التطبيقات App Set ID للتحليلات الخاصة بالمطور وسيناريوهات منع الاحتيال.

لاكتشاف أنماط التنفيذ الخاصة بإحالة أندرويد وخطوط الروابط العميقة، يرجى مراجعة توثيق OpoInstall.

المواد ذات الصلة

• المفاهيم: دورة حياة معرف الإعلانات، إذن ملف البيان AD_ID، استخراج الخيط الخلفي، التعامل مع المعرفات الصفرية

• التقنيات: خدمات Google Play، واجهة برمجة التطبيقات AdvertisingIdClient، واجهة برمجة تطبيقات Google Play Install Referrer، حزمة تطوير نرمجيات OpoInstall Android SDK

• المعايير: سياسات مطوري Google Play، تغييرات سلوك Android 13، معيار UUID لبروتوكول IETF RFC 4122

• واجهات برمجة التطبيقات والفئات: AdvertisingIdClient، AdvertisingIdClient.Info، AppSetIdClient، واجهة سياق OpoInstall Context API

الوثائق الرسمية

• توثيق AdvertisingIdClient لخدمات Google Play

• تغييرات سلوك Android 13 الخاصة بمعرف الإعلانات

• دليل مطوري أندرويد حول أفضل الممارسات للمعرفات الفريدة

• مساعدة وحدة تحكم Google Play بشأن سياسة معرف الإعلانات