تحديد التكلفة في اليوم

تستخدم إطار عمل GTAF مفتاح المستخدم لتحديد المشترك عند التواصل مع DPA. يمكن للتطبيقات التي يمكنها الوصول إلى رقم MSISDN الخاص بالمستخدم استخدام هذا الرقم كـ user_key. من ناحية أخرى، تحتاج التطبيقات التي لا يمكنها الوصول إلى رقم MSISDN إلى إنشاء معرّف خطة مشغّل شبكة الجوّال (CPID) بدون الكشف عن رقم MSISDN الخاص بالمستخدم. في ما يلي، سنشرح الآلية التي تحدّد معرّف CPID.

مسار مكالمة CPID

الشكل 2: مسار المكالمة لإنشاء CPID

  1. يستخدم أحد تطبيقات Google في الجهاز تطبيقًا داخليًا من Google لواجهة برمجة التطبيقات من أجل استرداد عنوان URL لنقطة نهاية CPID من GTAF. يتم تحديد هوية مشغّل شبكة الجوّال باستخدام عنوان IP العام الخاص بالجهاز ورمز البلد (MCC) ورمز شبكة الجوّال (MNC) لشريحة SIM النشطة. في حالة مشغّلي شبكات الجوّال الافتراضية (MVNO)، سيستخدم Google اسم موفّر الخدمة (SPN) وGID1 لتحديد مشغّل شبكة الجوّال الافتراضية.
  2. يرسل العميل طلب GET HTTP إلى نقطة نهاية CPID. يمكن للمشغّل إتاحة إرسال الطلب عبر HTTPS.
  3. يجوز للمشغّل استخدام وظيفة فحص الحزمة الكاملة لتحديد الطلب وإدراج رقم هاتف المستخدم في الطلب كعنوان HTTP.
  4. تتلقّى نقطة نهاية CPID الطلب، وتنشئ CPID، وتعرض CPID لجهاز المستخدم مع وقت البقاء (TTL) الذي يوضّح المدة التي يمكن لجهاز المستخدم استخدام CPID خلالها.

يمكن للمشغّل أيضًا استخدام عناوين IP بدلاً من أسماء النطاقات في عنوان URL لنقطة نهاية CPID إذا كان ذلك مفضّلاً. قد تكون عناوين IP في مساحة عناوين خاصة، ولكن يجب أن تكون متاحة لعملاء Google داخل شبكة المشغّل.

على المشغّل تقديم المعلومات التالية إلى Google كجزء من عملية الإعداد:

  1. عنوان URL الخاص بمعرّف الشريك (CPID_URL) الذي ستتواصل معه التطبيقات للحصول على معرّفات الشركاء. يجب توفير عنوان URL واحد من النوع CPID_URL، ولكن يمكن للمشغّل توفير عناوين URL متعددة لزيادة مدى التوفّر.
  2. قائمة بادئات عناوين IP التي يملكها المشغّل ورمز البلد الذي يتمّ فيه تشغيل شبكة الجوّال (MCC) ورموز الشبكة التي يتمّ فيها تشغيل شبكة الجوّال(MNC) التي يريد المشغّل ربطها بعناوين URL الخاصة بمعرّف مقدّم المحتوى (CPID). إذا كان مشغّل الشبكة يستخدم اسم موفّر الخدمة (SPN) أو المعرّف GID1 للتمييز بين مشغّلي شبكات الجوّال الافتراضية (MVNO) في شبكته، على مشغّل الشبكة تقديم هذه المعلومات أيضًا. ستستخدم Google هذه المعلومات لمطابقة العملاء مع نقاط النهاية المقابلة لمعرّف CPID، كما هو موضّح في الخطوة 1 من الشكل 2.

يكون تنسيق الطلب كما يلي: GET CPID_URL لأسباب قديمة، يجب أن تكون نقطة نهاية CPID قادرة على التعامل مع طلب مثل ما يلي:

GET CPID_URL?app={app_id}

يمكن لنقطة نهاية CPID تجاهل مَعلمة عنوان URL {app_id} عند إنشاء CPID. ومع ذلك، يجب أن يكون قادرًا على التعامل مع طلب يحتوي على المَعلمة.

قد يتضمّن الطلب إلى نقطة نهاية CPID العنوان Accept-Language. في حال تضمين العنوان، يجب أن تستخدم السلاسل القابلة للقراءة في التحديثات التي يرسلها DPA باستخدام Mobile Data Plan Sharing API الإعدادات المتوفّرة في طلب CPID.

في كل مرة يرسل فيها العميل طلب GET CPID_URL، يجب أن يتلقّى معرّفًا جديدًا. إذا تم إنشاء CPID بنجاح، يجب أن يعرض نقطة نهاية CPID استجابة 200 OK. يجب أن يحتوي نص الاستجابة على مثال CPIDResponse.

{
    "cpid": "<CPID_string>",
    "ttlSeconds": 2592000
}

يجب أن يكون معرّف المحتوى الذي تم إرجاعه صالحًا لمدة ttlSeconds ثانية حتى إذا طلب المشترك معرّفات محتوى أخرى بعد ذلك. تنصح Google باستخدام قيمة TTL تبلغ 30 يومًا، ولكن ليس أقل من 14 يومًا للحصول على أفضل تجربة للمستخدم. ستعمل GTAF على ترميز معرّف CPID وفقًا RFC2396 في المكالمات اللاحقة إلى DPA.

إنشاء معرّف CPID

الطريقة المُقترَحة التي يمكن لنقطة نهاية CPID اتّباعها لإنشاء CPID هي:

CPID_string = Base64(AES(MSISDN + TimeStamp + language, secret))

تجمع نقطة نهاية CPID بين رقم MSISDN واللغة التي يرسلها العميل في عنوان Accept-Language وطابع زمني عالي الدقة، ثم تشفّرها باستخدام خوارزمية AES وباستخدام secretkey. يجب أن يتوافق الطابع الزمني مع وقت انتهاء صلاحية معرّف المحتوى الشريك (CPID). ويتم ترميز الناتج المشفّر باستخدام Base64. بالإضافة إلى ذلك، عند استخدام معرّف المحتوى الخاص بالشريك في عنوان URL، يجب أن يكون عنوان URL بترميز عنوان URL للتعامل مع الأحرف الخاصة (/+=) المستخدَمة في Base64. ويجب أن يكون معرّف الشريك (CPID) بترميز عنوان URL، خاصةً عندما تستدعي أداة GTAF "اتفاقية معالجة البيانات" أو عندما تستدعي "اتفاقية معالجة البيانات" واجهة برمجة التطبيقات "مشاركة خطة بيانات الجوّال".

بناءً على حالة مشغّل معيّن، قد يكون من الصعب تنفيذ نقطة نهاية CPID. من التحديات التي نواجهها بشكل متكرر عدم توفّر إمكانية الوصول إلى رقم MSISDN في نقطة نهاية CPID. يسرّنا أن نشاركك الدروس المستفادة من عملية إعداد المشغّلين. يُرجى التواصل معنا إذا واجهت أي مشاكل.

مساحة تخزين CPID

لا يلزم تخزين معرّف CPID تم إنشاؤه باستخدام الآلية الموضّحة أعلاه في قاعدة بيانات. يمكن استخلاص المعلومات ذات الصلة بالتعامل مع المكالمات الواردة إلى "هيئة حماية البيانات" من معرّف CPID.

  1. عندما تتلقّى &quot;اتفاقية معالجة البيانات&quot; طلبًا من GTAF بشأن حالة خطة أو عروض، يمكن استخلاص رقم MSISDN من خلال فك تشفير CPID واستخراج رقم MSISDN.
  2. يمكن تحديد وقت انتهاء صلاحية CPID من خلال فك تشفير CPID ثم استخراج الطابع الزمني لانتهاء الصلاحية.

متطلبات التوفّر والسعة

إذا لم يتمكّن العملاء من استرداد معرّف CPID، لن يتمكّنوا من الوصول إلى أي معلومات من واجهة برمجة التطبيقات الخاصة بخطة بيانات الجوّال. لهذا السبب، على المشغّل اتّخاذ التدابير اللازمة لضمان توفّر نقطة نهاية CPID. وتشمل هذه الإجراءات توفير عدة مثيلات لنقطة نهاية CPID ووظائف DPI، وتوفير تكرار مادي وموقعي وشبكي لكلتا الوظيفتين، والتأكّد من كفاية موارد النظام وسعته. بالإضافة إلى ذلك، يجب أن تتوفّر سعة كافية في نقطة نهاية CPID وفي وظيفة DPI التي تُدرِج العنوان للتعامل مع عدد طلبات CPID التي يرسلها جميع عملاء Google. يمكن لنقطة نهاية CPID استخدام قيم أكبر في الحقل ttlSeconds لتقليل معدّل تكرار إنشاء معرّفات CPID.

حالات الأخطاء

في حال حدوث خطأ، يجب أن تعرض نقطة نهاية CPID خطأ HTTP مع نص استجابة يجب أن يحتوي على مثال ErrorResponse. يجب أن تتضمّن رسالة الخطأ الجيدة معلومات يمكن أن تساعد في تصحيح الخطأ. على سبيل المثال، في حال انتهاء صلاحية CPID، سيساعدنا تضمين وقت إنشاء CPID ووقت انتهاء صلاحيته في التأكّد من أنّ نقطة نهاية CPID تعمل على النحو المطلوب.

{
    "errorMessage": "<error message>",
    "cause": "USER_ROAMING"
}

يجب أن تعرض نقطة نهاية CPID ما يلي حسب السيناريو:

  1. إذا تم تلقّي طلب CPID لمستخدم لا ينتمي إلى شبكة المشغّل (على سبيل المثال، مستخدم ينتمي إلى مشغّل آخر ولكنّه يتجوّل على الشبكة التي يقدّمها نقطة نهاية CPID هذه) أو لم يوافق على مشاركة معلومات خطة البيانات مع Google، يجب أن تعرض نقطة نهاية CPID رمز حالة HTTP 403 مع USER_ROAMING أو USER_OPT_OUT أو INELIGIBLE_FOR_SERVICE كسبب.
  2. إذا تم تلقّي طلب CPID يتضمّن رقم هاتف غير صالح، يجب أن تعرض نقطة النهاية CPID ‎ رمز HTTP 400 مع سبب الخطأ INVALID_NUMBER.
  3. إذا كان الطلب إلى نقطة نهاية CPID مكتوبًا بشكل غير صحيح بأي طريقة أخرى، يجب أن تعرض نقطة نهاية CPID الرمز HTTP 400 مع تحديد ERROR_CAUSE_UNSPECIFIED كسبب.
  4. بالنسبة إلى أسباب الخطأ الأخرى، يمكن استخدام أي رمز خطأ HTTP متوافق. على وجه الخصوص، يُعدّ الخطأ HTTP 500 سببًا مناسبًا لأي عطل داخلي في نقطة نهاية CPID.