Data Plan Agent API, Data Plan Agent API

انگیزه

همانطور که در نمای کلی ذکر شد، بسته به موارد استفاده ای که اپراتور می خواهد پشتیبانی کند، DPA باید ترکیبی از Google Mobile Data Plan Sharing API و Data Plan Agent API را پیاده سازی کند. این سند، Data Plan Agent API را توصیف می‌کند که Google از آن برای شناسایی طرح‌های داده تلفن همراه کاربر، بازیابی اطلاعات مربوط به این طرح‌ها و خرید طرح‌های داده استفاده می‌کند.

احراز هویت

قبل از اینکه GTAF بتواند تماس بگیرد، DPA باید GTAF را احراز هویت کند. به عنوان بخشی از فرآیند ورود اپراتور، ما اعتبار گواهینامه DPA SSL را بررسی خواهیم کرد. ما در حال حاضر به استفاده از OAuth2 برای احراز هویت متقابل نیاز داریم. لطفاً برای جزئیات بیشتر در مورد نحوه احراز هویت GTAF خود با DPA به Data Plan Agent Authentication مراجعه کنید.

بین المللی شدن

درخواست‌های GTAF به DPA شامل یک هدر Accept-Language است که زبانی را نشان می‌دهد که رشته‌های قابل خواندن توسط انسان (مثلاً توضیحات طرح) باید در آن باشد. علاوه بر این، پاسخ‌های DPA (PlanStatus، PlanOffers) شامل یک فیلد زبان کد الزامی است که مقدار آن BCP-47 است. کد زبان (به عنوان مثال، "en-US") پاسخ.

اگر DPA از زبان درخواستی کاربر پشتیبانی نمی کند، می تواند از یک زبان پیش فرض استفاده کند و از قسمت languageCode برای نشان دادن انتخاب خود استفاده کند.

توضیحات API

GTAF هنگام پرس و جو از DPA اپراتور از کلید کاربر استفاده می کند که مشترک اپراتور را شناسایی می کند. وقتی GTAF از طرف برنامه هایی که به MSISDN دسترسی دارند از DPA درخواست می کند، GTAF ممکن است از MSISDN استفاده کند. در سطح بالایی، Data Plan Agent API پیشنهادی شامل اجزای زیر است:

  1. مکانیزم برای استعلام وضعیت طرح داده های کاربر.
  2. مکانیسمی برای پرس و جو از DPA برای ارائه طرح داده به کاربر.
  3. مکانیزم ایجاد تغییرات در طرح داده کاربر (به عنوان مثال، خرید یک طرح جدید).
  4. مکانیزمی برای اشتراک گذاری CPID که می تواند برای ارسال اعلان ها به کاربران استفاده شود.
  5. مکانیزمی برای به اشتراک گذاشتن انتخاب های کاربر در مورد ثبت نام در سرویس ما.

بقیه این سند در مورد هر یک از این مؤلفه های API توضیح می دهد. مگر اینکه صریحاً ذکر شده باشد، همه ارتباطات باید از طریق HTTPS (با یک گواهی معتبر DPA SSL) انجام شوند. بسته به ویژگی‌های واقعی که پشتیبانی می‌شوند، یک اپراتور ممکن است تمام یا زیرمجموعه‌ای از این مؤلفه‌های API را پیاده‌سازی کند.

تعامل GTAF-DPA

GTAF-DPA Interaction

شکل 4. جریان تماس برای درخواست و دریافت اطلاعات طرح داده کاربر.

شکل 4 جریان تماس مرتبط با مشتری را نشان می دهد که در مورد وضعیت طرح داده کاربر و سایر اطلاعات طرح داده پرس و جو می کند. این جریان تماس برای تماس‌های API ایجاد شده توسط مشتری در UE به اشتراک گذاشته می‌شود.

  1. مشتری با تماس با یک Google API خصوصی، وضعیت طرح داده و/یا سایر اطلاعات را درخواست می‌کند. کلاینت شامل کلید کاربر در درخواست GTAF می شود.
  2. GTAF از کلید کاربر و شناسه کلاینت برای پرس و جو از DPA اپراتور استفاده می کند. شناسه های مشتری پشتیبانی شده mobiledataplan و youtube هستند. هنگامی که DPA تماسی با یکی از این شناسه های مشتری دریافت می کند، باید با اطلاعات طرحی که می تواند توسط مشتری استفاده شود پاسخ دهد.
  3. GTAF اطلاعات درخواستی را به مشتری برمی گرداند و اطلاعات طرح توسط GTAF تا زمان انقضا مشخص شده توسط DPA ذخیره می شود.

مراحل 1 و 3 در شکل 4 APIهای Google خصوصی هستند و بنابراین بیشتر توضیح داده نشده اند. مرحله 2 یک API عمومی است که در ادامه توضیح داده می شود. هنگامی که این تماس‌های API از GTAF ارائه می‌شود، DPA باید به هدر HTTP Cache-Control: no-cache احترام بگذارد.

استعلام وضعیت طرح داده

GTAF برای دریافت وضعیت طرح درخواست HTTP زیر را صادر می کند:

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

سرویس گیرنده ای که GTAF از طرف آن با DPA تماس می گیرد با استفاده از CLIENT_ID شناسایی می شود. بسته به توافق بین مشتری و اپراتور Google، DPA می‌تواند پاسخ به GTAF را سفارشی کند. در صورت موفقیت، 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 از طرف آن با DPA تماس می گیرد با استفاده از CLIENT_ID شناسایی می شود. بسته به توافق بین مشتری و اپراتور Google، DPA می‌تواند پاسخ به GTAF را سفارشی کند. پارامتر زمینه اختیاری زمینه برنامه ای را که درخواست در آن انجام می شود فراهم می کند. معمولاً این رشته ای است که برنامه از طریق 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 اول باید ارائه شوند. اگر برنامه درخواستی پیشنهادات ماژول Mobile Data Plan باشد که بخشی از خدمات Google Play است، GTAF تنها تا 50 طرح را به اشتراک می گذارد. این برای اطمینان از تجربه کاربری خوب برای کاربران خدمات Google Play است.

پیشنهادهای upsell دارای filterTag ها به عنوان یک پارامتر اختیاری هستند که آرایه ای از برچسب ها به هر پلان متصل می شود. همه این تگ‌های فیلتر باید با برچسبی مطابقت داشته باشند که یک شی در داخل فیلتر است. Filter یک شی سطح اول است که حاوی تاپل است . Filter فهرست تلفیقی از فیلترهایی است که در رابط کاربری ارائه می‌شوند. کاربر می تواند با کلیک بر روی DisplayText فیلتر کند. تگ مربوط به displayText برای فیلتر کردن پیشنهادات استفاده می شود.

توجه داشته باشید که اپراتور باید مکانیزمی برای انجام درخواست خرید برای هر پیشنهاد ارائه شده به کاربر داشته باشد. با استفاده از گزینه formOfPayment در پاسخ می توان مکانیزمی را که از طریق آن کاربر برای هر خریدی هزینه دریافت می کند، با GTAF ارتباط برقرار کرد.

خرید داده

API طرح خرید نحوه خرید GTAF را از طریق DPA تعریف می کند. GTAF تراکنش را برای خرید یک طرح داده به DPA آغاز می کند. درخواست باید شامل یک شناسه تراکنش منحصر به فرد (transactionId) برای ردیابی درخواست ها و جلوگیری از اجرای تراکنش های تکراری باشد. DPA باید با پاسخ موفقیت/شکست پاسخ دهد.

درخواست معامله

هنگامی که یک درخواست از یک مشتری دریافت کرد، GTAF یک درخواست POST را به DPA ارسال می کند. آدرس درخواست این است:

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.
}

پاسخ معامله

DPA باید یک پاسخ 200-OK فقط برای یک تراکنش با موفقیت اجرا شده یا یک تراکنش در صف تولید کند. لطفاً موارد خطا را برای پاسخ مورد انتظار در صورت بروز خطا ببینید. در صورت تراکنش در صف، DPA فقط باید وضعیت تراکنش را پر کند و سایر فیلدها را در پاسخ خالی بگذارد. 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 ثبت می‌کند. اگر مشتری CPID را با موفقیت در GTAF ثبت کند، GTAF با استفاده از فراخوانی API زیر، CPID را در DPA ثبت می کند:

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

که در آن userKey CPID است و تنها CLIENT_ID پشتیبانی شده mobiledataplan است. متن درخواست نمونه‌ای از RegisterCpidRequest است و شامل زمانی است که پس از آن نمی‌توان از CPID برای ارسال اعلان‌ها استفاده کرد و به نظر می‌رسد:

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

این API فقط برای اپراتورهایی مرتبط است که به دنبال پشتیبانی از ماژول Mobile Data Plan در خدمات Google Play هستند. به منظور ارسال مطمئن اعلان ها به کاربر، DPA MAY آخرین CPID ثبت شده را برای هر کاربر ذخیره می کند. لطفاً برای راهنمایی در مورد نحوه استفاده از CPID ثبت شده برای ارسال اعلان ها، به انتخاب CPID مراجعه کنید.

اگر DPA با موفقیت CPID را با کاربر مرتبط کند و دائماً آن را ذخیره کند، DPA باید یک پاسخ 200-OK ایجاد کند. لطفاً موارد خطا را برای پاسخ مورد انتظار در صورت بروز خطا ببینید.

GTAF ممکن است درخواست زیر را برای انتقال ترجیح رضایت کاربر به شرکت مخابراتی صادر کند.

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

که در آن userKey یا CPID یا MSISDN است. بدنه درخواست نمونه ای از SetConsentStatusRequest است. در صورت موفقیت آمیز بودن، بدنه پاسخ باید خالی باشد.

هر تماس از GTAF به DPA از شرایط خدمات مشتری Google که تماس برقرار می کند پیروی می کند. بسته به برنامه‌هایی که DPA به دنبال پشتیبانی از آن است، این به اپراتور بستگی دارد که تصمیم بگیرد آیا DPA این API را پیاده‌سازی می‌کند یا خیر. اگر DPA اجرای API رضایت را انتخاب کند، DPA باید آخرین وضعیت رضایت را برای هر کاربر ذخیره کند. لطفاً برای راهنمایی در مورد نحوه استفاده از اطلاعات وضعیت رضایت، به انتخاب CPID مراجعه کنید.

در صورت موفقیت، DPA باید HTTP 200 OK را با بدنه پاسخ خالی برگرداند. لطفاً موارد خطا را برای پاسخ مورد انتظار در صورت بروز خطا ببینید.

،

انگیزه

همانطور که در نمای کلی ذکر شد، بسته به موارد استفاده ای که اپراتور می خواهد پشتیبانی کند، DPA باید ترکیبی از Google Mobile Data Plan Sharing API و Data Plan Agent API را پیاده سازی کند. این سند، Data Plan Agent API را توصیف می‌کند که Google از آن برای شناسایی طرح‌های داده تلفن همراه کاربر، بازیابی اطلاعات مربوط به این طرح‌ها و خرید طرح‌های داده استفاده می‌کند.

احراز هویت

قبل از اینکه GTAF بتواند تماس بگیرد، DPA باید GTAF را احراز هویت کند. به عنوان بخشی از فرآیند ورود اپراتور، ما اعتبار گواهینامه DPA SSL را بررسی خواهیم کرد. ما در حال حاضر به استفاده از OAuth2 برای احراز هویت متقابل نیاز داریم. لطفاً برای جزئیات بیشتر در مورد نحوه احراز هویت GTAF خود با DPA به Data Plan Agent Authentication مراجعه کنید.

بین المللی شدن

درخواست‌های GTAF به DPA شامل یک هدر Accept-Language است که زبانی را نشان می‌دهد که رشته‌های قابل خواندن توسط انسان (مثلاً توضیحات طرح) باید در آن باشد. علاوه بر این، پاسخ‌های DPA (PlanStatus، PlanOffers) شامل یک فیلد زبان کد الزامی است که مقدار آن BCP-47 است. کد زبان (به عنوان مثال، "en-US") پاسخ.

اگر DPA از زبان درخواستی کاربر پشتیبانی نمی کند، می تواند از یک زبان پیش فرض استفاده کند و از قسمت languageCode برای نشان دادن انتخاب خود استفاده کند.

توضیحات API

GTAF هنگام پرس و جو از DPA اپراتور از کلید کاربر استفاده می کند که مشترک اپراتور را شناسایی می کند. وقتی GTAF از طرف برنامه هایی که به MSISDN دسترسی دارند از DPA درخواست می کند، GTAF ممکن است از MSISDN استفاده کند. در سطح بالایی، Data Plan Agent API پیشنهادی شامل اجزای زیر است:

  1. مکانیزم برای استعلام وضعیت طرح داده های کاربر.
  2. مکانیسمی برای پرس و جو از DPA برای ارائه طرح داده به کاربر.
  3. مکانیزم ایجاد تغییرات در طرح داده کاربر (به عنوان مثال، خرید یک طرح جدید).
  4. مکانیزمی برای اشتراک گذاری CPID که می تواند برای ارسال اعلان ها به کاربران استفاده شود.
  5. مکانیزمی برای به اشتراک گذاشتن انتخاب های کاربر در مورد ثبت نام در سرویس ما.

بقیه این سند در مورد هر یک از این مؤلفه های API توضیح می دهد. مگر اینکه صریحاً ذکر شده باشد، همه ارتباطات باید از طریق HTTPS (با یک گواهی معتبر DPA SSL) انجام شوند. بسته به ویژگی‌های واقعی که پشتیبانی می‌شوند، یک اپراتور ممکن است تمام یا زیرمجموعه‌ای از این مؤلفه‌های API را پیاده‌سازی کند.

تعامل GTAF-DPA

GTAF-DPA Interaction

شکل 4. جریان تماس برای درخواست و دریافت اطلاعات طرح داده کاربر.

شکل 4 جریان تماس مرتبط با مشتری را نشان می دهد که در مورد وضعیت طرح داده کاربر و سایر اطلاعات طرح داده پرس و جو می کند. این جریان تماس برای تماس‌های API ایجاد شده توسط مشتری در UE به اشتراک گذاشته می‌شود.

  1. مشتری با تماس با یک Google API خصوصی، وضعیت طرح داده و/یا سایر اطلاعات را درخواست می‌کند. کلاینت شامل کلید کاربر در درخواست GTAF می شود.
  2. GTAF از کلید کاربر و شناسه کلاینت برای پرس و جو از DPA اپراتور استفاده می کند. شناسه های مشتری پشتیبانی شده mobiledataplan و youtube هستند. هنگامی که DPA تماسی با یکی از این شناسه های مشتری دریافت می کند، باید با اطلاعات طرحی که می تواند توسط مشتری استفاده شود پاسخ دهد.
  3. GTAF اطلاعات درخواستی را به مشتری برمی گرداند و اطلاعات طرح توسط GTAF تا زمان انقضا مشخص شده توسط DPA ذخیره می شود.

مراحل 1 و 3 در شکل 4 APIهای Google خصوصی هستند و بنابراین بیشتر توضیح داده نشده اند. مرحله 2 یک API عمومی است که در ادامه توضیح داده می شود. هنگامی که این تماس‌های API از GTAF ارائه می‌شود، DPA باید به هدر HTTP Cache-Control: no-cache احترام بگذارد.

استعلام وضعیت طرح داده

GTAF برای دریافت وضعیت طرح درخواست HTTP زیر را صادر می کند:

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

سرویس گیرنده ای که GTAF از طرف آن با DPA تماس می گیرد با استفاده از CLIENT_ID شناسایی می شود. بسته به توافق بین مشتری و اپراتور Google، DPA می‌تواند پاسخ به GTAF را سفارشی کند. در صورت موفقیت، 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 از طرف آن با DPA تماس می گیرد با استفاده از CLIENT_ID شناسایی می شود. بسته به توافق بین مشتری و اپراتور Google، DPA می‌تواند پاسخ به GTAF را سفارشی کند. پارامتر زمینه اختیاری زمینه برنامه کاربردی را فراهم می کند که درخواست در آن انجام می شود. معمولاً این رشته ای است که برنامه از طریق 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 اول باید ارائه شوند. اگر برنامه درخواستی پیشنهادات ماژول Mobile Data Plan باشد که بخشی از خدمات Google Play است، GTAF تنها تا 50 طرح را به اشتراک می گذارد. این برای اطمینان از تجربه کاربری خوب برای کاربران خدمات Google Play است.

پیشنهادهای upsell دارای filterTag ها به عنوان یک پارامتر اختیاری هستند که آرایه ای از برچسب ها به هر پلان متصل می شود. همه این تگ‌های فیلتر باید با برچسبی مطابقت داشته باشند که یک شی در داخل فیلتر است. Filter یک شی سطح اول است که حاوی تاپل است . Filter فهرست تلفیقی از فیلترهایی است که در رابط کاربری ارائه می‌شوند. کاربر می تواند با کلیک بر روی DisplayText فیلتر کند. تگ مربوط به displayText برای فیلتر کردن پیشنهادات استفاده می شود.

توجه داشته باشید که اپراتور باید مکانیزمی برای انجام درخواست خرید برای هر پیشنهاد ارائه شده به کاربر داشته باشد. با استفاده از گزینه formOfPayment در پاسخ می توان مکانیزمی را که از طریق آن کاربر برای هر خریدی هزینه دریافت می کند، با GTAF ارتباط برقرار کرد.

خرید داده

API طرح خرید نحوه خرید GTAF را از طریق DPA تعریف می کند. GTAF تراکنش را برای خرید یک طرح داده به DPA آغاز می کند. درخواست باید شامل یک شناسه تراکنش منحصر به فرد (transactionId) برای ردیابی درخواست ها و جلوگیری از اجرای تراکنش های تکراری باشد. DPA باید با پاسخ موفقیت/شکست پاسخ دهد.

درخواست معامله

هنگامی که یک درخواست از یک مشتری دریافت کرد، GTAF یک درخواست POST را به DPA ارسال می کند. آدرس درخواست این است:

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.
}

پاسخ معامله

DPA باید یک پاسخ 200-OK فقط برای یک تراکنش با موفقیت اجرا شده یا یک تراکنش در صف تولید کند. لطفاً موارد خطا را برای پاسخ مورد انتظار در صورت بروز خطا ببینید. در صورت تراکنش در صف، DPA فقط باید وضعیت تراکنش را پر کند و سایر فیلدها را در پاسخ خالی بگذارد. 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 ثبت می‌کند. اگر مشتری CPID را با موفقیت در GTAF ثبت کند، GTAF با استفاده از فراخوانی API زیر، CPID را در DPA ثبت می کند:

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

که در آن userKey CPID است و تنها CLIENT_ID پشتیبانی شده mobiledataplan است. بدنه درخواست نمونه‌ای از RegisterCpidRequest است و حاوی زمانی است که پس از آن نمی‌توان از CPID برای ارسال اعلان‌ها استفاده کرد و به نظر می‌رسد:

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

این API فقط برای اپراتورهایی مرتبط است که به دنبال پشتیبانی از ماژول Mobile Data Plan در خدمات Google Play هستند. به منظور ارسال مطمئن اعلان ها به کاربر، DPA MAY آخرین CPID ثبت شده را برای هر کاربر ذخیره می کند. لطفاً برای راهنمایی در مورد نحوه استفاده از CPID ثبت شده برای ارسال اعلان ها، به انتخاب CPID مراجعه کنید.

اگر DPA با موفقیت CPID را با کاربر مرتبط کند و دائماً آن را ذخیره کند، DPA باید یک پاسخ 200-OK ایجاد کند. لطفاً موارد خطا را برای پاسخ مورد انتظار در صورت بروز خطا ببینید.

GTAF ممکن است درخواست زیر را برای انتقال ترجیح رضایت کاربر به شرکت مخابراتی صادر کند.

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

که در آن userKey یا CPID یا MSISDN است. بدنه درخواست نمونه ای از SetConsentStatusRequest است. در صورت موفقیت آمیز بودن، بدنه پاسخ باید خالی باشد.

هر تماس از GTAF به DPA از شرایط خدمات مشتری Google که تماس برقرار می کند پیروی می کند. بسته به برنامه‌هایی که DPA به دنبال پشتیبانی از آن است، این به اپراتور بستگی دارد که تصمیم بگیرد آیا DPA این API را پیاده‌سازی می‌کند یا خیر. اگر DPA اجرای API رضایت را انتخاب کند، DPA باید آخرین وضعیت رضایت را برای هر کاربر ذخیره کند. لطفاً برای راهنمایی در مورد نحوه استفاده از اطلاعات وضعیت رضایت، به انتخاب CPID مراجعه کنید.

در صورت موفقیت، DPA باید HTTP 200 OK را با بدنه پاسخ خالی برگرداند. لطفاً موارد خطا را برای پاسخ مورد انتظار در صورت بروز خطا ببینید.