بما أنّه يمكنك الآن جمع عناوين البريد الإلكتروني وأرقام الهواتف الخاصة بالمستخدمين وأنّ تطبيقك يتضمّن حزمة تطوير البرامج (SDK)
Google Analytics لـ Firebase، يمكنك استخدام الحزمتَين لبدء
قياس الإحالات الناجحة.
استدعاء واجهة برمجة التطبيقات
اطلب واجهة برمجة التطبيقات لقياس الإحالات الناجحة باستخدام عنوان البريد الإلكتروني أو رقم الهاتف
الذي تمت الموافقة عليه من الخطوة 1، والذي يُستخدَم لقياس الإحالات الناجحة للإعلانات، بدون
السماح لأي معلومات تحدّد الهوية الشخصية بمغادرة جهاز المستخدم.
استورِد وحدة FirebaseAnalytics وأدخِل عنوان البريد الإلكتروني أو رقم الهاتف
إلى واجهة برمجة التطبيقات initiateOnDeviceConversionMeasurement().
importFirebaseAnalytics// ...// If you're using an email address....Analytics.initiateOnDeviceConversionMeasurement(emailAddress:"example@gmail.com")// If you're using a phone number....Analytics.initiateOnDeviceConversionMeasurement(phoneNumber:"+15555555555")
Objective-C
استورِد وحدة FirebaseAnalytics وأدخِل عنوان البريد الإلكتروني إلى initiateOnDeviceConversionMeasurementWithEmailAddress: API أو رقم الهاتف إلى initiateOnDeviceConversionMeasurementWithPhoneNumber: API.
@importFirebaseAnalytics;// ...// If you're using an email address....[FIRAnalyticsinitiateOnDeviceConversionMeasurementWithEmailAddress:@"example@gmail.com"];// If you're using a phone number....[FIRAnalyticsinitiateOnDeviceConversionMeasurementWithPhoneNumber:@"+15555555555"];
Unity
استورِد مساحة الاسم Firebase.Analytics وأدخِل عنوان البريد الإلكتروني إلى InitiateOnDeviceConversionMeasurementWithEmailAddress() API أو رقم الهاتف إلى InitiateOnDeviceConversionMeasurementWithPhoneNumber() API:
usingFirebase.Analytics;// ...// If you're using an email address....FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithEmailAddress("example@gmail.com");// If you're using a phone number....FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithPhoneNumber("+15555555555");
استخدام عنوان بريد إلكتروني أو رقم هاتف مجزّأ
ستقبل واجهة برمجة التطبيقات عناوين البريد الإلكتروني وأرقام الهواتف التي تم تجزئتها باستخدام خوارزمية SHA256. يمكنك
الحفاظ على التحكّم في بيانات المستخدمين من خلال إجراء عملية التجزئة في الرمز البرمجي
قبل إجراء طلبات إلى حزمة SDK.
لاستخدام بيانات الاعتماد المجزّأة، عليك تطبيع العناوين والأرقام وتجزئتها باستخدام دالّة SHA256، ثمّ طلب البيانات من واجهة برمجة التطبيقات.
توحيد عناوين البريد الإلكتروني وأرقام الهواتف
بالنسبة إلى عناوين البريد الإلكتروني، تفترض واجهة برمجة التطبيقات Google Analytics أنّه يتم تنفيذ عملية معالجة معيّنة قبل تطبيق SHA256، لذا اتّبِع الخطوات التالية لمعالجة بياناتك:
حوِّل عنوان البريد الإلكتروني بالكامل إلى أحرف صغيرة.
إذا كان عنوان البريد الإلكتروني ينتهي بالنطاق @googlemail.com، استبدِل النطاق
@googlemail.com بالنطاق @gmail.com.
بالنسبة إلى العناوين التي تنتهي بالنطاق @gmail.com (بما في ذلك العناوين التي تم تعديلها في
الخطوة السابقة):
أزِل جميع النقاط من جزء اسم المستخدم.
أجرِ الاستبدالات التالية في جزء اسم المستخدم:
استبدِل الحرف l بالحرف I أو i أو الرقم 1.
استبدِل الحرف o بالرقم 0.
استبدِل الحرف z بالرقم 2.
استبدِل الحرف s بالرقم 5.
على سبيل المثال، بعد التسويّة:
an.email.user0125@googlemail.com يصبح anemalluserolzs@gmail.com
CAPSUSER0125@provider.net يصبح capsuser0125@provider.net
بالنسبة إلى أرقام الهواتف، يجب أن تكون الأرقام بتنسيق E.164 (أي
بادئة بعلامة +، و1 إلى 3 أرقام لرمز البلد، و12 رقمًا بحد أقصى لرقم المشترك)
قبل التجزئة باستخدام SHA256.
يُرجى العِلم أنّ عناوين البريد الإلكتروني أو أرقام الهواتف المجزّأة باستخدام SHA256 يجب أن يكون طولها 32 بايت
وليست سلسلة سداسية عشرية.
استدعاء واجهة برمجة التطبيقات باستخدام بيانات اعتماد مجزّأة
Swift
استورِد وحدة FirebaseAnalytics وأدخِل عنوان البريد الإلكتروني أو رقم الهاتف
إلى واجهة برمجة التطبيقات initiateOnDeviceConversionMeasurement().
importFirebaseAnalytics// ...// If you're using an email address....Analytics.initiateOnDeviceConversionMeasurement(hashedEmailAddress:hashedEmailAddress)// If you're using a phone number....Analytics.initiateOnDeviceConversionMeasurement(hashedPhoneNumber:hashedPhoneNumber)
Objective-C
استورِد وحدة FirebaseAnalytics وأدخِل عنوان البريد الإلكتروني إلى initiateOnDeviceConversionMeasurementWithHashedEmailAddress: API أو رقم الهاتف إلى initiateOnDeviceConversionMeasurementWithHashedPhoneNumber:
API.
@importFirebaseAnalytics;// ...// If you're using an email address....[FIRAnalyticsinitiateOnDeviceConversionMeasurementWithHashedEmailAddress:hashedEmailAddress];// If you're using a phone number....[FIRAnalyticsinitiateOnDeviceConversionMeasurementWithHashedPhoneNumber:hashedPhoneNumber];
Unity
استورِد مساحة الاسم Firebase.Analytics وأدخِل عنوان البريد الإلكتروني إلى InitiateOnDeviceConversionMeasurementWithHashedEmailAddress() API أو
رقم الهاتف إلى InitiateOnDeviceConversionMeasurementWithHashedPhoneNumber() API:
usingFirebase.Analytics;// ...// If you're using an email address....FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithHashedEmailAddress(hashedEmailAddress);// If you're using a phone number....FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithHashedPhoneNumber(hashedPhoneNumber);
التحقّق من خلال سجلات تصحيح الأخطاء في Xcode (اختياري)
إذا فعّلت وضع تصحيح الأخطاء، تأكَّد من أنّه بعد طلب واجهة برمجة التطبيقات لبدء القياس، تظهر رسالة مثل رسالة السجلّ التالية في وحدة تحكّم تصحيح أخطاء Xcode:
إذا فعّلت وضع تصحيح الأخطاء وأدرجت -DebugOnDeviceConversionMeasurement
مَعلمة التشغيل، سيؤدي استدعاء initiateOnDeviceConversionMeasurement() API
إلى محاكاة مطابقة.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["Step 3: Initiate on-device conversion measurement using Google Analytics\n\n\u003cbr /\u003e\n\n|--------------------------------------------------------------------------------------------------------------|\n| Introduction: [Measure iOS Ads conversions](/docs/tutorials/ads-ios-on-device-measurement/index-first-party) |\n| Step 1: [Implement a sign-in experience](/docs/tutorials/ads-ios-on-device-measurement/step-1) \u003cbr /\u003e |\n| [Step 2: Integrate Google Analytics](/docs/tutorials/ads-ios-on-device-measurement/step-2) |\n| **Step 3: Initiate on-device conversion measurement using Google Analytics** \u003cbr /\u003e |\n| Step 4: [Troubleshoot and handle common issues](/docs/tutorials/ads-ios-on-device-measurement/step-4) |\n\n\u003cbr /\u003e\n\nNow that you can collect users' email addresses and phone numbers and your app has the\nGoogle Analytics for Firebase SDK, you can use the two to start\nmeasuring conversions.\n\nCall the API\n\nCall the conversion measurement API with the consented email address or phone\nnumber from Step 1, which is used for ads conversion measurement, without\nallowing any personally identifiable information to leave the user device.\n\nThere are two ways to initiate measurement:\n\n- [Using credentials](#use-plain-text-credentials)\n- [Using hashed credentials](#use-hashed-credentials)\n\nUse email address or phone number \n\nSwift\n\nImport the `FirebaseAnalytics` module and pass in the email address or phone\nnumber to the `initiateOnDeviceConversionMeasurement()` API.\n**Note:** The `initiateOnDeviceConversionMeasurement(emailAddress:)` and `initiateOnDeviceConversionMeasurement(phoneNumber:)` methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored. \n\n```swift\nimport FirebaseAnalytics\n\n// ...\n// If you're using an email address....\nAnalytics.initiateOnDeviceConversionMeasurement(emailAddress: \"example@gmail.com\")\n// If you're using a phone number....\nAnalytics.initiateOnDeviceConversionMeasurement(phoneNumber: \"+15555555555\")\n```\n\nObjective-C\n\nImport the `FirebaseAnalytics` module and pass in the email address to the\n`initiateOnDeviceConversionMeasurementWithEmailAddress:` API or the phone\nnumber to the `initiateOnDeviceConversionMeasurementWithPhoneNumber:` API.\n**Note:** The `initiateOnDeviceConversionMeasurementWithEmailAddress:` and `initiateOnDeviceConversionMeasurementWithPhoneNumber:` methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored. \n\n```objective-c\n@import FirebaseAnalytics;\n\n// ...\n// If you're using an email address....\n[FIRAnalytics initiateOnDeviceConversionMeasurementWithEmailAddress:@\"example@gmail.com\"];\n// If you're using a phone number....\n[FIRAnalytics initiateOnDeviceConversionMeasurementWithPhoneNumber:@\"+15555555555\"];\n```\n\nUnity\n\nImport the `Firebase.Analytics` namespace and pass in the email address to the\n`InitiateOnDeviceConversionMeasurementWithEmailAddress()` API or the phone\nnumber to the `InitiateOnDeviceConversionMeasurementWithPhoneNumber()` API:\n**Note:** The `InitiateOnDeviceConversionMeasurementWithEmailAddress()` and `InitiateOnDeviceConversionMeasurementWithPhoneNumber()` methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored. \n\n```c#\nusing Firebase.Analytics;\n\n// ...\n// If you're using an email address....\nFirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithEmailAddress(\"example@gmail.com\");\n// If you're using a phone number....\nFirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithPhoneNumber(\"+15555555555\");\n```\n| **Note:** The best practice is to call the API once per install and as close as possible to the login.\n| **Important:** Be aware that if an intended in-app action or event happens *immediately* after a user email or phone registration, consider implementing a small time delay between initiating on-device conversion measurement and logging the event.\n\nUse a hashed email address or phone number\n\nThe API will accept email addresses and phone numbers hashed with SHA256. You\ncan maintain control of your user's data by performing the hashing in your code\nbefore making calls to the SDK.\n\nTo use hashed credentials, normalize addresses and numbers, hash them with\nSHA256, then call the API.\n\nNormalize email addresses and phone numbers\n\nFor **email addresses** , the Google Analytics API assumes that a\nparticular normalization is performed before SHA256 is applied, so follow these\nsteps to normalize your data:\n\n1. Convert the entire email address to lowercase.\n\n2. If the email address ends in domain *@googlemail.com* , replace the\n *@googlemail.com* domain with *@gmail.com*.\n\n3. For addresses ending in domain *@gmail.com* (including those modified in\n the previous step):\n\n 1. Remove all periods from the username portion.\n\n 2. Make the following substitutions in the username portion:\n\n - For letters I or i, or digit 1, substitute letter l\n - For digit 0, substitute letter o\n - For digit 2, substitute letter z\n - For digit 5, substitute letter s\n\nFor example, after normalization:\n\n- `an.email.user0125@googlemail.com` becomes `anemalluserolzs@gmail.com`\n- `CAPSUSER0125@provider.net` becomes `capsuser0125@provider.net`\n\nFor **phone numbers**, numbers must already be in E.164 format (that is,\nprefix with +, 1-3 digits for country code, max 12 digits for subscriber number)\nprior to hashing with SHA256.\n\nNote that the hashed SHA256 email or phone numbers must be 32 bytes long\nand not a hexadecimal string.\n\nCall the API with hashed credentials \n\nSwift\n\nImport the `FirebaseAnalytics` module and pass in the email address or phone\nnumber to the `initiateOnDeviceConversionMeasurement()` API.\n**Note:** The `initiateOnDeviceConversionMeasurement(hashedEmailAddress:)` and `initiateOnDeviceConversionMeasurement(hashedPhoneNumber:)` methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored. \n\n```swift\nimport FirebaseAnalytics\n\n// ...\n// If you're using an email address....\nAnalytics.initiateOnDeviceConversionMeasurement(hashedEmailAddress: hashedEmailAddress)\n// If you're using a phone number....\nAnalytics.initiateOnDeviceConversionMeasurement(hashedPhoneNumber: hashedPhoneNumber)\n```\n\nObjective-C\n\nImport the `FirebaseAnalytics` module and pass in the email address to the\n`initiateOnDeviceConversionMeasurementWithHashedEmailAddress:` API or the phone\nnumber to the `initiateOnDeviceConversionMeasurementWithHashedPhoneNumber:`\nAPI.\n**Note:** The `initiateOnDeviceConversionMeasurementWithHashedEmailAddress:` and `initiateOnDeviceConversionMeasurementWithHashedPhoneNumber:` methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored. \n\n```objective-c\n@import FirebaseAnalytics;\n\n// ...\n// If you're using an email address....\n[FIRAnalytics initiateOnDeviceConversionMeasurementWithHashedEmailAddress:hashedEmailAddress];\n// If you're using a phone number....\n[FIRAnalytics initiateOnDeviceConversionMeasurementWithHashedPhoneNumber:hashedPhoneNumber];\n```\n\nUnity\n\nImport the `Firebase.Analytics` namespace and pass in the email address to the\n`InitiateOnDeviceConversionMeasurementWithHashedEmailAddress()` API or the\nphone number to the `InitiateOnDeviceConversionMeasurementWithHashedPhoneNumber()` API:\n**Note:** The `InitiateOnDeviceConversionMeasurementWithHashedEmailAddress()` and `InitiateOnDeviceConversionMeasurementWithHashedPhoneNumber()` methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored. \n\n```c#\nusing Firebase.Analytics;\n\n// ...\n// If you're using an email address....\nFirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithHashedEmailAddress(hashedEmailAddress);\n// If you're using a phone number....\nFirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithHashedPhoneNumber(hashedPhoneNumber);\n```\n| **Note:** The best practice is to call the API once per install and as close as possible to the login.\n| **Important:** Be aware that if an intended in-app action or event happens *immediately* after a user email or phone registration, consider implementing a small time delay between initiating on-device conversion measurement and logging the event.\n\nVerify with Xcode debug logs (optional)\n\nIf you enabled debug mode, after calling the initiate measurement API, ensure\nthat a message like the following log message appears in the Xcode debug\nconsole: \n\n [FirebaseAnalytics][I-ACS023225] Initiated on-device conversion measurement\n\nIf you enabled debug mode and included the `-DebugOnDeviceConversionMeasurement`\nlaunch argument, then calling the `initiateOnDeviceConversionMeasurement()` API\nwill simulate a match. \n\n [FirebaseAnalytics][I-ACS023229] On-device conversion measurement found a match\n\n\u003cbr /\u003e\n\n*** ** * ** ***\n\n\u003cbr /\u003e\n\n[arrow_back_ios**Step 2** : Integrate Google Analytics](/docs/tutorials/ads-ios-on-device-measurement/step-2)\n[**Step 4** : Troubleshoot and handle common issuesarrow_forward_ios](/docs/tutorials/ads-ios-on-device-measurement/step-4)\n\n\u003cbr /\u003e\n\n*** ** * ** ***"]]
