واجهة برمجة تطبيقات وكيل خطة البيانات

الحافز

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

المصادقة

قبل أن يتمكّن "مدير إعلانات Google" من الاتصال، على "هيئة حماية البيانات" المصادقة على "هيئة حماية البيانات". كجزء من عملية الإعداد لتشغيل المشغّل، سنتحقّق من صلاحية شهادة طبقة المقابس الآمنة (DPA). نطلب حاليًا استخدام OAuth2 للمصادقة المتبادلة. يُرجى الاطّلاع على مصادقة وكيل بيانات البيانات للحصول على تفاصيل حول كيفية مصادقة "أداة مزامنة دليل Google Cloud" لنفسها مع "هيئة حماية البيانات".

التوافق مع أسواق عالمية

تتضمّن طلبات "إطار عمل الشفافية والموافقة" (DAF) إلى "هيئة حماية البيانات" عنوان قبول اللغة يشير إلى اللغة التي يجب أن تكون فيها السلاسل المقروئة للبشر (مثل أوصاف الخطة). إضافةً إلى ذلك، تتضمّن استجابات هيئة حماية البيانات (PlanStatus وPlanOffers) حقل اللغة مطلوبًا وتكون قيمته رمز اللغة BCP-47 (مثل "en-US").

في حال لم تكن "هيئة حماية البيانات" متوافقة مع اللغة التي طلبها المستخدم، يمكنه استخدام لغة تلقائية واستخدام حقلlanguageCode للإشارة إلى اختياره.

وصف واجهة برمجة التطبيقات

يستخدم GTAF مفتاح المستخدم، الذي يحدد مشتركًا في عامل التشغيل، عند طلب البحث في DPA لـ عامل التشغيل. عندما يُرسِل "GTAF" طلب بحث عن "هيئة حماية البيانات" نيابةً عن التطبيقات التي يمكنها الوصول إلى MSISDN، قد يستخدم "GTAF MAY" رقم MSISDN. على مستوى عالٍ، تتألف واجهة برمجة تطبيقات وكيل خطة البيانات المقترحة من المكوّنات التالية:

1. آلية لطلب البحث عن حالة خطة بيانات المستخدمين
2. آلية لطلب تعديل معالجة البيانات من أجل خطط خطة البيانات للمستخدم.
3. آلية إجراء تغييرات على خطة بيانات المستخدم (مثل شراء خطة جديدة).
4. آلية مشاركة أرقام CPID التي يمكن استخدامها لإرسال إشعارات إلى المستخدمين
5. آلية لمشاركة خيارات المستخدمين بشأن ما إذا كان عليهم الاشتراك في خدمتنا.

يشرح الجزء المتبقي من هذا المستند كل مكوّن من مكونات واجهة برمجة التطبيقات هذه. يجب أن تتم جميع الاتصالات عبر بروتوكول HTTPS (بدون شهادة طبقة المقابس الآمنة) صالحة، ما لم تتم الإشارة صراحةً إلى ذلك صراحةً. استنادًا إلى الميزات الفعلية التي يتم اعتمادها، قد يختار المشغّل تنفيذ كل مكوّنات واجهة برمجة التطبيقات هذه أو مجموعة فرعية منها.

تفاعل GTAF-DPA

الشكل 4. مسار الاتصال لطلب معلومات خطة بيانات المستخدم واستلامها.

يوضح الشكل 4 تدفق المكالمات المرتبط بعميل يستفسر عن حالة خطة البيانات للمستخدم، فضلاً عن معلومات أخرى عن خطة البيانات. تتم مشاركة مسار الاتصال هذا مع طلبات البيانات من واجهة برمجة التطبيقات التي يشغّلها العميل في UE.

1. يطلب العميل حالة خطة البيانات و/أو معلومات أخرى من خلال استدعاء واجهة برمجة تطبيقات Google خاصة. يتضمّن العميل مفتاح المستخدم في الطلب إلى GTAF.
2. تستخدم أداة GTAF مفتاح المستخدم ومعرّف العميل للاستعلام عن معامل التشغيل (DPA) في عامل التشغيل's. معرّفات البرامج المتوافقة هي mobiledataPlan وyoutube. عندما تتلقّى "هيئة حماية البيانات" مكالمة مع أحد معرّفات العملاء هذه، يجب أن تستجيب لمعلومات الخطة التي يمكن للعميل استخدامها.
3. يعرض GTAF المعلومات المطلوبة للعميل ويخزّن معلومات الخطة مؤقتًا بواسطة GTAF حتى وقت انتهاء الصلاحية الذي تحدّده هيئة حماية البيانات.

الخطوتين 1 و3 في الشكل 4 هما واجهات برمجة تطبيقات Google خاصة، وبالتالي لا يتم وصفهما أكثر من ذلك. الخطوة 2 هي واجهة برمجة تطبيقات عامة موضّحة في ما يلي. يجب أن تلتزم"هيئة حماية البيانات"برأس HTTP Cache-Control: no-cache عند عرض طلبات البيانات من واجهة برمجة التطبيقات هذه من GTAF.

حالة خطة بيانات الطلبات

يُصدر GTAF طلب HTTP التالي للحصول على حالة الخطة:

GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID

يتم تحديد العميل الذي يتواصل من أجله"هيئة حماية البيانات"نيابةً عنه باستخدام"CLIENT_ID". بناءً على الاتفاقية المُبرَمة بين عميل Google ومشغّل "هيئة حماية البيانات"، يمكن لهيئة حماية البيانات تخصيص الاستجابة لـ GTAF. في حال نجاح هذا الإجراء، يجب أن تعرض "هيئة حماية البيانات" HTTP 200 OK مع نص استجابة يمثّل PlanStatus. يُرجى الاطّلاع على حالات الخطأ لمعرفة الاستجابة المتوقعة في حالة الأخطاء.

{
  "plans": [{
    "planName": "ACME1",
    "planId": "1",
    "planCategory": "PREPAID",
    "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
    "planModules": [{
      "moduleName": "Giga Plan", // req.
      "trafficCategories": ["GENERIC"],
      "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
      "overUsagePolicy": "BLOCKED",
      "maxRateKbps": "1500",
      "description": "1GB for a month", // req.
      "coarseBalanceLevel": "HIGH_QUOTA"
    }]
  }],
  "languageCode": "en-US", // req.
  "expireTime": "2018-06-14T08:41:27-07:00", // req.
  "updateTime": "2018-06-07T07:41:22-07:00", // req.
  "title": "Prepaid Plan"
  "planInfoPerClient": {
    "youtube": {
      "rateLimitedStreaming": {
        "maxMediaRateKbps": 256
      }
    }
  }
}

بالنسبة إلى خطط الدفع عند الاستخدام، يجب أن يكون expirationTime تاريخ تكرار الخطة (أي عند إعادة تحميل رصيد البيانات أو إعادة تحميله).

يمكن أن تحتوي كل وحدة خطة على فئة متعددة للزيارات في وحدة الخطة (PMTCs)لوضع نموذج تتم فيه مشاركة وحدة الخطة بين تطبيقات متعددة، مثل 500 ميغابايت للألعاب والموسيقى). يتم تحديد الرموز المميّزة التالية للبيع بالتجزئة: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. من المتوقّع أن يتواصل فريق التشغيل مع فِرق Google الفردية للموافقة على مجموعة فئات الزيارات ومعانيها ذات الصلة بتطبيقات Google المختلفة.

عروض أسعار طلبات البحث

يُصدر GTAF طلب HTTP التالي للحصول على عروض الخطط من عامل التشغيل:

GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}

يتم تحديد العميل الذي يتواصل من أجله "هيئة حماية البيانات" نيابةً عنه باستخدام "CLIENT_ID". بناءً على الاتفاقية المُبرَمة بين عميل Google ومشغّل "هيئة حماية البيانات"، يمكن لهيئة حماية البيانات تخصيص الاستجابة لـ GTAF. توفّر معلّمة السياق الاختيارية سياق التطبيق الذي يتم تقديم الطلب فيه. وعادةً ما تكون هذه السلسلة هي عبارة عن تطبيق يمرِّره إلى عامل التشغيل من خلال GTAF.

في حال نجاح هذا الإجراء، يجب أن تعرض "هيئة حماية البيانات" HTTP 200 OK مع نص استجابة يمثّل PlanOffer. يُرجى الاطّلاع على حالات الخطأ لمعرفة الاستجابة المتوقّعة في حال حدوث أخطاء.

{
    "offers": [
      {
        "planName": "ACME Red", // req.
        "planId": "turbulent1", // req.
        "planDescription": "Unlimited Videos for 30 days.", // req.
        "promoMessage": "Binge watch videos.",
        "languageCode": "en_US", // req.
        "overusagePolicy": "BLOCKED",
        "cost": { // req.
          "currencyCode": "INR",
          "units": "300",
          "nanos": 0
        },
        "duration": "2592000s",
        "offerContext": "YouTube",
        "trafficCategories": ["VIDEO"],
        "quotaBytes": "9223372036850",
        "filterTags": ["repurchase", "all"]
      }
    ],
    "filters" : [
      {
        "tag": "repurchase",
        "displayText": "REPURCHASE PLANS"
      },
      {
        "tag": "all",
        "displayText": "ALL PLANS"
      }
    ]
    "expireTime": "2019-03-04T00:06:07Z" // req.
}

قد يحدّد ترتيب خطط البيانات في مصفوفة offers الترتيب الذي يتم به تقديم خطط البيانات للمستخدمين. علاوة على ذلك، إذا كان التطبيق يمكنه تقديم خطط x فقط بسبب واجهة المستخدم أو قيود أخرى، وكانت الاستجابة تحتوي على y > x، فلن يتم تقديم سوى خطط x الأولى. يشارك GTAF ما يصل إلى 50 خطة فقط إذا كان طلب البحث عن العروض هو وحدة خطة بيانات الجوّال التي هي جزء من خدمات Google Play. ويضمن هذا الإجراء تقديم تجربة جيدة لمستخدمي "خدمات Google Play".

تحتوي عروض الارتقاء في المبيعات على فلاتر مهمّة اختيارية، وهي عبارة عن مصفوفة من العلامات المرفقة بكل خطة من الخطط. ويجب أن تتطابق كل علامات الفلترة هذه مع العلامة التي تمثّل عنصرًا داخل الفلتر. Filter هو كائن من المستوى الأول يحتوي على tuple<tag, displaytextportraitquot;">;. Filter هو قائمة موحّدة للفلاتر التي سيتم عرضها على واجهة المستخدم. ويمكن للمستخدم إجراء فلترة بالنقر على TextDisplay. يتم استخدام العلامة المقابلة لـ displayText لفلترة العروض.</tag,>

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

شراء البيانات

تحدّد واجهة برمجة تطبيقات خطة الشراء كيف يمكن لـ GTAF شراء الخطط من خلال "تعديل بنود معالجة البيانات". تُنشئ GTAF المعاملة لشراء خطة بيانات واحدة لهيئة حماية البيانات. يجب أن يتضمّن الطلب معرّف معاملة فريدًا (transactionId) لتتبّع الطلبات وتجنّب تكرار تنفيذ المعاملات. يجب أن تردّ "هيئة حماية البيانات" باستجابة ناجحة/تعذّر إتمامها.

طلب المعاملة

بعد أن يتلقّى طلبًا من عميل، يُصدِّر GTAF طلب POST إلى "هيئة حماية البيانات". عنوان URL للطلب هو:

POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID

حيث userKey هو CPID أو MSISDN. نص الطلب هو نسخة افتراضية من TransactionRequest الذي يتضمن الحقول التالية:

{
  "planId": string,         // Id of plan to be purchased. Copied from
                            // offers.planId field returned from a
                            // Upsell Offer request,
                            // if available. (req.).
  "transactionId": string,  // Unique request identifier (req.)
  "offerContext": string,   // Copied from from the
                            // offers.offerContext, if available.
                            // (opt.)
  "callbackUrl": string     // URL that the DPA can call back with response once
                            // it has handled the request.
}

الردّ على المعاملة

تنشئ "تعديل بنود معالجة البيانات" استجابة 200-OK فقط لمعاملة تم تنفيذها بنجاح أو لمعاملة في قائمة الانتظار فقط. يُرجى الاطّلاع على حالات الخطأ للاستجابة المتوقعة في حال حدوث أخطاء. في حال كانت المعاملة مرتبطة بقائمة الانتظار، لن تعبّر هيئة حماية البيانات إلا عن حالة المعاملة وترك حقول أخرى في الرد فارغًا. يجب أن تطلب "هيئة حماية البيانات" من "هيئة حماية البيانات" (GTAF) ردًّا بعد معالجة المعاملة قيد الانتظار. نص الاستجابة هو مثال على TransactionResponse الذي يتضمّن التفاصيل التالية:

{
  "transactionStatus": "SUCCESS",

  "purchase": {
    "planId": string,               // copied from request. (req.)
    "transactionId": string,        // copied from request. (req.)
    "transactionMessage": string,   // status message. (opt.)
    "confirmationCode": string,     // DPA-generated confirmation code
                                    // for successful transaction. (opt.)
    "planActivationTime" : string,  // Time when plan will be activated,
                                    // in timestamp format. (opt.)
  },

  // walletInfo is populated with the balance left in the user's account.
  "walletBalance": {
    "currencyCode": string,       // 3-letter currency code defined in ISO 4217.
    "units": string,              // Whole units of the currency amount.
    "nanos": number               // Number of nano units of the amount.
  }
}

في حال عدم إدراج planActivationTime، يفترض GTAF SHALL أنه تم تفعيل الخطة.

تسجيل رقم CPID

إذا تلقّى العميل الذي يدعم الإشعارات معرّف CPID جديدًا من نقطة نهاية CPID، يتم تسجيل معرّف CPID لدى GTAF إذا كانت بنود البرنامج تسمح بـ GTAF. لإجراء ذلك، إذا سجّل العميل CPID بنجاح مع GTAF، حينئذٍ سيسجّل CPAF معرّف CPID لدى DPA باستخدام استدعاء واجهة برمجة التطبيقات التالي:

POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID

حيث userKey هو معرّف CPID والوحيد CLIENT_ID الوحيد هو mobiledataPlan. يشكّل نص الطلب مثالاً على RegisterCvidRequest ويحتوي على الوقت الذي لا يمكن بعدها استخدام معرّف CPID لإرسال الإشعارات ويظهر على النحو التالي:

{"staleTime": "2017-01-29T01:00:03.14159Z"}

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

ستنشئ "هيئة حماية البيانات" استجابة 200-OK إذا ربطت "هيئة حماية البيانات" بنجاح رقم CPID بالمستخدم وخزّنه باستمرار. يُرجى الاطّلاع على حالات الخطأ لمعرفة الاستجابة المتوقّعة في حال حدوث أخطاء.

الموافقة

قد يُصدر GTAF MAY الطلب التالي لتمرير تفضيل موافقة المستخدم إلى مشغّل شبكة الجوّال.

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

حيث userKey هو CPID أو MSISDN. نص الطلب هو نسخة افتراضية من SetConsentStatusRequest. إذا كانت هذه الإجابة ناجحة، يجب أن يكون نص الاستجابة فارغًا.

تتبع كل مكالمة من "هيئة إعلانات المركبات" (GTAF) إلى "هيئة حماية البيانات" بنود خدمة برنامج Google الذي يُجري المكالمة. اعتمادًا على التطبيقات التي تتطلّع "هيئة حماية البيانات" إلى استخدامها، تقع على عاتق عامل التشغيل مسؤولية تحديد ما إذا كانت "هيئة حماية البيانات" تنفذ "واجهة برمجة التطبيقات" هذه. إذا اختارت "هيئة حماية البيانات" تنفيذ واجهة برمجة التطبيقات للموافقة، يجب أن تخزّن "هيئة حماية البيانات" أحدث حالة موافقة لكل مستخدم. يُرجى الاطّلاع على اختيار معرّف CPID للحصول على إرشادات عن كيفية استخدام معلومات حالة الموافقة.

في حال نجاح هذا الإجراء، يجب أن تعرض "هيئة حماية البيانات" HTTP 200 OK مع نص استجابة فارغ. يُرجى الاطّلاع على حالات الخطأ لمعرفة الاستجابة المتوقعة في حال حدوث أخطاء.