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

الحافز

كما هو موضّح في النظرة العامة، اعتمادًا على حالات الاستخدام التي يريد مشغّل شبكة الجوّال توفيرها، يجب أن تنفّذ DPA مزيجًا من واجهة برمجة التطبيقات Google Mobile Data Plan Sharing API وواجهة برمجة التطبيقات Data Plan Agent API. يوضّح هذا المستند واجهة برمجة التطبيقات Data Plan Agent التي ستستخدمها Google لتحديد خطط بيانات الجوّال الخاصة بالمستخدم واسترداد معلومات حول هذه الخطط وشرائها.

المصادقة

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

التدويل

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

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

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

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

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

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

التفاعل بين إطار عمل تقييم التهديدات العالمية (GTAF) واتفاقية معالجة البيانات (DPA)

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

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

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

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

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

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

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

يتم تحديد العميل الذي تتواصل GTAF معه نيابةً عن "هيئة حماية البيانات" باستخدام CLIENT_ID. بناءً على الاتفاقية بين عميل Google والمشغّل، يمكن لـ "اتفاقية معالجة البيانات" تخصيص الردّ على "إطار الشفافية والموافقة على مستوى العالم". في حال النجاح، يجب أن تعرض DPA الرمز 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 ميغابايت للألعاب والموسيقى). يتم تحديد فئات PMTC التالية مسبقًا: 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}

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

في حال النجاح، يجب أن تعرض DPA الرمز 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".

تتضمّن عروض البيع بسعر أعلى filterTags كمعلَمة اختيارية وهي عبارة عن مصفوفة من العلامات المرفقة بكل خطة. يجب أن تتطابق كل filterTags مع العلامة التي هي عبارة عن عنصر داخل الفلتر. ‫Filter هو عنصر من المستوى الأول يحتوي على tuple<tag, displaytext="">. ‏Filter هي قائمة موحّدة بالفلاتر التي سيتم عرضها على واجهة المستخدم. يمكن للمستخدم الفلترة من خلال النقر على DisplayText. يتم استخدام العلامة المطابقة لـ displayText من أجل فلترة العروض.</tag,>

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

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

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

طلب المعاملة

بعد تلقّي طلب من أحد العملاء، يرسل إطار الشفافية والموافقة العالمي طلب 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.
}

ردّ المعاملة

يجب أن تنشئ &quot;وكالة معالجة البيانات&quot; استجابة 200-OK فقط للمعاملات التي تم تنفيذها بنجاح أو المعاملات التي تم وضعها في قائمة الانتظار. يُرجى الاطّلاع على حالات الأخطاء لمعرفة الردّ المتوقّع في حال حدوث أخطاء. في حال كانت المعاملة في قائمة الانتظار، يجب أن يملأ DPA حالة المعاملة فقط ويترك الحقول الأخرى في الرد فارغة. يجب أن يعاود موفّر خدمة الدفع الاتصال بـ 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 أنّه تم تفعيل الخطة.

تسجيل CPID

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

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

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

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

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

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

الموافقة

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

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

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

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

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