برنامج تعليمي: قياس الإحالات الناجحة في "إعلانات iOS"

الخطوة 3: بدء قياس الإحالات الناجحة على الجهاز فقط باستخدام Google Analytics

بعد أن أصبح بإمكانكم جمع عناوين البريد الإلكتروني وأرقام الهواتف الخاصة بالمستخدمين وتضمين تطبيقكم حزمة SDK Google Analytics لـ Firebase، يمكنكم استخدام هاتين الميزتَين لبدء قياس الإحالات الناجحة.

استدعاء واجهة برمجة التطبيقات

يمكنكم استدعاء واجهة برمجة التطبيقات لقياس الإحالات الناجحة باستخدام عنوان البريد الإلكتروني أو رقم الهاتف اللذَين تمت الموافقة عليهما في الخطوة 1، واللذَين يُستخدَمان لقياس الإحالات الناجحة في الإعلانات، بدون السماح بمغادرة أي معلومات تحديد هوية شخصية لجهاز المستخدم.

هناك طريقتان لبدء عملية القياس:

• استخدام بيانات الاعتماد
• استخدام بيانات الاعتماد المجزّأة

استخدام عنوان البريد الإلكتروني أو رقم الهاتف

import FirebaseAnalytics

// ...
// If you're using an email address....
Analytics.initiateOnDeviceConversionMeasurement(emailAddress: "example@gmail.com")
// If you're using a phone number....
Analytics.initiateOnDeviceConversionMeasurement(phoneNumber: "+15555555555")

@import FirebaseAnalytics;

// ...
// If you're using an email address....
[FIRAnalytics initiateOnDeviceConversionMeasurementWithEmailAddress:@"example@gmail.com"];
// If you're using a phone number....
[FIRAnalytics initiateOnDeviceConversionMeasurementWithPhoneNumber:@"+15555555555"];

using Firebase.Analytics;

// ...
// If you're using an email address....
FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithEmailAddress("example@gmail.com");
// If you're using a phone number....
FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithPhoneNumber("+15555555555");

أفضل الممارسات لاستدعاء واجهة برمجة التطبيقات

لضمان قياس الإحالات الناجحة على الجهاز فقط بدقة وبشكلٍ مستمر، يمكنكم إجراء أيّ مما يلي:

استدعاء واجهة برمجة التطبيقات عند كل تحديث للتطبيق (مقترَح)

Google Analytics for Firebase SDK version 12.1.0 and later includes improvements to on-device conversion measurement. لضمان تطبيق هذه التحسينات على جميع المستخدمين، بما في ذلك المستخدمون الذين سجّلوا الدخول قبل تحديث تطبيقكم، من الضروري استدعاء واجهة برمجة التطبيقات initiateOnDeviceConversionMeasurement مرة أخرى بعد تحديث التطبيق.

على وجه التحديد، لا يتم تضمين المستخدمين الذين سجّلوا الدخول قبل تحديث تطبيقكم إلى الإصدار 12.1.0 من حزمة SDK في نطاق القياس المحسّن إلى أن يتم استدعاء واجهة برمجة التطبيقات initiateOnDeviceConversionMeasurement مرة أخرى لهم. بدون التحقّق من تحديث التطبيق، لن يحدث ذلك إلا إذا سجّلوا الخروج ثم سجّلوا الدخول مرة أخرى.

أفضل الممارسات هي استدعاء واجهة برمجة التطبيقات للمستخدمين الذين سجّلوا الدخول مرة واحدة على الأقل لكل إصدار من التطبيق. يمكنكم تنفيذ عملية تحقّق عند إطلاق التطبيق لاستدعاء واجهة برمجة التطبيقات فقط عندما يتغيّر إصدار التطبيق منذ آخر استدعاء.

// On app launch if the app version has changed, call the API with the first-party data
// (for example: email address, phone number, hashed email address, hashed phone number).
let cachedAppVersion = UserDefaults.standard.string(forKey: "cachedAppVersion")
let currentAppVersion =
  Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String

if cachedAppVersion != currentAppVersion {
let hashedEmailAddress = ...
Analytics.initiateOnDeviceConversionMeasurement(hashedEmailAddress: hashedEmailAddress)
UserDefaults.standard.set(currentAppVersion, forKey: "cachedAppVersion")
}

// On app launch if the app version has changed, call the API with the first-party data
// (for example: email address, phone number, hashed email address, hashed phone number).
NSString *cachedAppVersion =
  [[NSUserDefaults standardUserDefaults] stringForKey:@"cachedAppVersion"];
NSString *currentAppVersion = [[NSBundle mainBundle]
  objectForInfoDictionaryKey:@"CFBundleShortVersionString"];

if (![cachedAppVersion isEqualToString:currentAppVersion]) {
NSString *hashedEmailAddress = ...
[FIRAnalytics initiateOnDeviceConversionMeasurementWithHashedEmailAddress:hashedEmailAddress];
[[NSUserDefaults standardUserDefaults] setObject:currentAppVersion
                                          forKey:@"cachedAppVersion"];
}

// On app launch if the app version has changed, call the API with the first-party data
// (for example: email address, phone number, hashed email address, hashed phone number).
string cachedAppVersion = PlayerPrefs.GetString("cached_app_version", "");
string currentAppVersion = Application.version;

if (cachedAppVersion != currentAppVersion) {
byte[] hashedEmailAddress = ...
FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithHashedEmailAddress(
    hashedEmailAddress);
PlayerPrefs.SetString("cached_app_version", currentAppVersion);
PlayerPrefs.Save();
}

استدعاء واجهة برمجة التطبيقات مباشرةً بعد تسجيل الدخول

يجب دائمًا استدعاء واجهة برمجة التطبيقات initiateOnDeviceConversionMeasurement مباشرةً بعد أن يسجّل المستخدم الدخول بنجاح أو يسجّل عنوان بريده الإلكتروني أو رقم هاتفه.

اعتبارات التوقيت للتسجيلات الجديدة

إذا حدث حدث إحالة ناجحة رئيسي مباشرةً بعد تسجيل المستخدم (واستدعيتم واجهة برمجة التطبيقات)، ننصحكم بتنفيذ تأخير بسيط (على سبيل المثال، خمس ثوانٍ) بين طلب بيانات من واجهة برمجة التطبيقات وتسجيل الحدث الرئيسي. يساعد ذلك في ضمان تهيئة القياس على الجهاز فقط بالكامل قبل تسجيل الحدث.

استخدام عنوان بريد إلكتروني أو رقم هاتف مجزّأَين

ستقبل واجهة برمجة التطبيقات عناوين البريد الإلكتروني وأرقام الهواتف المجزّأة باستخدام خوارزمية SHA256. يمكنكم الحفاظ على التحكّم في بيانات المستخدمين من خلال إجراء التجزئة في الرمز البرمجي قبل استدعاء حزمة SDK.

لاستخدام بيانات الاعتماد المجزّأة، عليكم تسوية العناوين والأرقام، ثم تجزئتها باستخدام خوارزمية SHA256، ثم استدعاء واجهة برمجة التطبيقات.

تسوية عناوين البريد الإلكتروني وأرقام الهواتف

بالنسبة إلى عناوين البريد الإلكتروني، تفترض واجهة برمجة تطبيقات Google Analytics إجراء تسوية معيّنة قبل تطبيق خوارزمية SHA256، لذا يُرجى اتّباع الخطوات التالية لتسوية بياناتكم:

1. تحويل عنوان البريد الإلكتروني بالكامل إلى أحرف صغيرة

2. إذا كان عنوان البريد الإلكتروني ينتهي بالنطاق ‎@googlemail.com، استبدِلوا النطاق ‎@googlemail.com بالنطاق ‎@gmail.com.

3. بالنسبة إلى العناوين التي تنتهي بالنطاق ‎@gmail.com (بما في ذلك العناوين المعدَّلة في الخطوة السابقة):

   1. أزيلوا جميع النقاط من جزء اسم المستخدم.

   2. أجروا عمليات الاستبدال التالية في جزء اسم المستخدم:

      • بالنسبة إلى الحرفَين I أو i أو الرقم 1، استبدِلوا الحرف l
      • بالنسبة إلى الرقم 0، استبدِلوا الحرف o
      • بالنسبة إلى الرقم 2، استبدِلوا الحرف z
      • بالنسبة إلى الرقم 5، استبدِلوا الحرف s

على سبيل المثال، بعد التسوية:

• an.email.user0125@googlemail.com يصبح anemalluserolzs@gmail.com
• CAPSUSER0125@provider.net يصبح capsuser0125@provider.net

بالنسبة إلى أرقام الهواتف، يجب أن تكون الأرقام بالتنسيق E.164 (أي، يجب أن تبدأ بعلامة +، وأن تتضمّن رمز البلد الذي يتألف من رقم واحد إلى ثلاثة أرقام، ورقم المشترك الذي يتألف من 12 رقمًا كحد أقصى) قبل تجزئتها باستخدام خوارزمية SHA256.

يُرجى العِلم أنّ عنوان البريد الإلكتروني أو رقم الهاتف المجزّأَين باستخدام خوارزمية SHA256 يجب أن يكونا بطول 32 بايت وليس سلسلة سداسية عشرية.

استدعاء واجهة برمجة التطبيقات باستخدام بيانات الاعتماد المجزّأة

import FirebaseAnalytics

// ...
// If you're using an email address....
Analytics.initiateOnDeviceConversionMeasurement(hashedEmailAddress: hashedEmailAddress)
// If you're using a phone number....
Analytics.initiateOnDeviceConversionMeasurement(hashedPhoneNumber: hashedPhoneNumber)

@import FirebaseAnalytics;

// ...
// If you're using an email address....
[FIRAnalytics initiateOnDeviceConversionMeasurementWithHashedEmailAddress:hashedEmailAddress];
// If you're using a phone number....
[FIRAnalytics initiateOnDeviceConversionMeasurementWithHashedPhoneNumber:hashedPhoneNumber];

using Firebase.Analytics;

// ...
// If you're using an email address....
FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithHashedEmailAddress(hashedEmailAddress);
// If you're using a phone number....
FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithHashedPhoneNumber(hashedPhoneNumber);

التأكّد من عملية التكامل

فعِّل وضع تصحيح الأخطاء. بعد استدعاء واجهة برمجة تطبيقات لقياس البيانات لبدء القياس، تأكَّدوا من ظهور رسالة مشابهة لرسالة مسجّلة التالية في وحدة تصحيح الأخطاء في Xcode:

[FirebaseAnalytics][I-ACS023225] Initiated on-device conversion measurement

إذا فعّلتم وضع تصحيح الأخطاء وأدرجتم وسيطة الإطلاق -DebugOnDeviceConversionMeasurement، سيؤدي استدعاء واجهة برمجة التطبيقات initiateOnDeviceConversionMeasurement() إلى محاكاة تطابق.

[FirebaseAnalytics][I-ACS023229] On-device conversion measurement found a match

arrow_back_iosالخطوة 2: دمج Google Analytics الخطوة 4: تحديد المشاكل الشائعة وحلّهاarrow_forward_ios