ডেটা প্ল্যান এজেন্ট API, ডেটা প্ল্যান এজেন্ট API

প্রেরণা

ওভারভিউতে উল্লিখিত হিসাবে, অপারেটর সমর্থন করতে চায় এমন ব্যবহারের ক্ষেত্রে নির্ভর করে, DPA-কে Google মোবাইল ডেটা প্ল্যান শেয়ারিং API এবং ডেটা প্ল্যান এজেন্ট API-এর সমন্বয় বাস্তবায়ন করতে হবে। এই দস্তাবেজটি ডেটা প্ল্যান এজেন্ট API বর্ণনা করে যা Google ব্যবহারকারীর মোবাইল ডেটা প্ল্যানগুলি সনাক্ত করতে, এই প্ল্যানগুলি সম্পর্কে তথ্য পুনরুদ্ধার করতে এবং ডেটা প্ল্যান কেনার জন্য ব্যবহার করবে৷

প্রমাণীকরণ

GTAF কল করার আগে, DPA অবশ্যই GTAF প্রমাণীকরণ করবে। অপারেটর অনবোর্ডিং প্রক্রিয়ার অংশ হিসাবে, আমরা DPA SSL শংসাপত্রের বৈধতা পরীক্ষা করব। আমরা বর্তমানে পারস্পরিক প্রমাণীকরণের জন্য OAuth2 ব্যবহার প্রয়োজন। GTAF কিভাবে DPA এর সাথে নিজেকে প্রমাণীকরণ করে তার বিস্তারিত জানার জন্য অনুগ্রহ করে ডেটা প্ল্যান এজেন্ট প্রমাণীকরণ দেখুন।

আন্তর্জাতিকীকরণ

ডিপিএ-র কাছে জিটিএএফ অনুরোধগুলির মধ্যে একটি গ্রহণ-ভাষা শিরোনাম রয়েছে যা নির্দেশ করে যে ভাষাটি মানুষের পঠনযোগ্য স্ট্রিংগুলি (যেমন, পরিকল্পনার বিবরণ) থাকা উচিত৷ আরও, ডিপিএ প্রতিক্রিয়াগুলি (প্ল্যানস্ট্যাটাস, প্ল্যানঅফার) একটি প্রয়োজনীয় ভাষাকোড ক্ষেত্র অন্তর্ভুক্ত করে যার মান হল BCP-47 প্রতিক্রিয়ার ভাষা কোড (যেমন, "en-US")।

DPA ব্যবহারকারীর অনুরোধ করা ভাষা সমর্থন না করলে, এটি একটি ডিফল্ট ভাষা ব্যবহার করতে পারে এবং তার পছন্দ নির্দেশ করার জন্য ভাষাকোড ক্ষেত্র ব্যবহার করতে পারে।

API বর্ণনা

GTAF ব্যবহারকারী কী ব্যবহার করে, যা অপারেটরের ডিপিএ জিজ্ঞাসা করার সময় অপারেটরের একজন গ্রাহককে সনাক্ত করে। যখন GTAF MSISDN-এ অ্যাক্সেস আছে এমন অ্যাপ্লিকেশনগুলির হয়ে DPA-কে জিজ্ঞাসা করছে, GTAF MSISDN ব্যবহার করতে পারে। উচ্চ স্তরে, প্রস্তাবিত ডেটা প্ল্যান এজেন্ট API নিম্নলিখিত উপাদানগুলি নিয়ে গঠিত:

1. ব্যবহারকারীর ডেটা প্ল্যান স্ট্যাটাস জিজ্ঞাসা করার প্রক্রিয়া।
2. ব্যবহারকারীর জন্য ডেটা প্ল্যান অফারগুলির জন্য DPA জিজ্ঞাসা করার প্রক্রিয়া৷
3. ব্যবহারকারীর ডেটা প্ল্যানে পরিবর্তন করার প্রক্রিয়া (যেমন, একটি নতুন প্ল্যান কেনা)।
4. ব্যবহারকারীদের বিজ্ঞপ্তি পাঠাতে ব্যবহার করা যেতে পারে যে CPID শেয়ার করার ব্যবস্থা.
5. আমাদের পরিষেবার জন্য সাইন আপ করতে হবে কিনা সে বিষয়ে ব্যবহারকারীর পছন্দগুলি ভাগ করার প্রক্রিয়া৷

এই নথির বাকি অংশ এই API উপাদানগুলির প্রতিটির উপর বিস্তারিত বর্ণনা করে। স্পষ্টভাবে উল্লেখ না করা পর্যন্ত, সমস্ত যোগাযোগ অবশ্যই HTTPS এর মাধ্যমে ঘটতে হবে (একটি বৈধ DPA SSL শংসাপত্র সহ)। সমর্থিত প্রকৃত বৈশিষ্ট্যগুলির উপর নির্ভর করে, একজন অপারেটর এই API উপাদানগুলির সমস্ত বা একটি উপসেট বাস্তবায়ন করতে বেছে নিতে পারে।

GTAF-DPA ইন্টারঅ্যাকশন

চিত্র 4. ব্যবহারকারীর ডেটা প্ল্যানের তথ্য অনুরোধ এবং গ্রহণ করার জন্য কল প্রবাহ।

চিত্র 4 ব্যবহারকারীর ডেটা প্ল্যান স্ট্যাটাস এবং অন্যান্য ডেটা প্ল্যান তথ্য সম্পর্কে একটি ক্লায়েন্ট অনুসন্ধানের সাথে যুক্ত কল প্রবাহকে চিত্রিত করে। এই কল ফ্লো UE-তে ক্লায়েন্ট দ্বারা ট্রিগার করা API কলগুলির জন্য ভাগ করা হয়।

1. ক্লায়েন্ট একটি ব্যক্তিগত Google API কল করে ডেটা প্ল্যান স্ট্যাটাস এবং/অথবা অন্যান্য তথ্যের অনুরোধ করে। ক্লায়েন্ট জিটিএএফ-এর কাছে অনুরোধে ব্যবহারকারী কী অন্তর্ভুক্ত করে।
2. GTAF ব্যবহারকারী কী এবং একটি ক্লায়েন্ট শনাক্তকারী ব্যবহার করে অপারেটরের DPA জিজ্ঞাসা করতে। সমর্থিত ক্লায়েন্ট শনাক্তকারী হল মোবাইলডেটাপ্ল্যান এবং ইউটিউব । যখন DPA এই ক্লায়েন্ট আইডেন্টিফায়ারগুলির মধ্যে একটির সাথে একটি কল পায়, তখন এটি অবশ্যই ক্লায়েন্টের দ্বারা ব্যবহার করা যেতে পারে এমন পরিকল্পনার তথ্য সহ সাড়া দিতে হবে।
3. GTAF ক্লায়েন্টকে অনুরোধ করা তথ্য ফেরত দেয় এবং DPA দ্বারা নির্দিষ্ট মেয়াদ শেষ না হওয়া পর্যন্ত প্ল্যান তথ্য GTAF দ্বারা ক্যাশ করা হয়।

চিত্র 4-এর ধাপ 1 এবং 3 হল ব্যক্তিগত Google API এবং তাই আর বর্ণনা করা হয়নি৷ ধাপ 2 এর পরে বর্ণিত একটি সর্বজনীন API। GTAF থেকে এই API কলগুলি পরিবেশন করার সময় DPA কে অবশ্যই Cache-Control: no-cache HTTP হেডারকে সম্মান করতে হবে।

ডেটা প্ল্যান স্ট্যাটাস জিজ্ঞাসা করা হচ্ছে

প্ল্যান স্ট্যাটাস পেতে 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 MB)। নিম্নলিখিত 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 ফেরত দিতে হবে একটি প্ল্যানঅফার প্রতিনিধিত্বকারী একটি প্রতিক্রিয়া বডি সহ। ত্রুটির ক্ষেত্রে প্রত্যাশিত প্রতিক্রিয়ার জন্য দয়া করে ত্রুটির কেসগুলি দেখুন৷

{
    "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 অ্যারেতে ডেটা প্ল্যান(গুলি) এর ক্রম ব্যবহারকারীদের কাছে ডেটা প্ল্যান(গুলি) উপস্থাপিত করার ক্রম নির্ধারণ করতে পারে৷ আরও, যদি UI বা অন্যান্য সীমাবদ্ধতার কারণে অ্যাপ্লিকেশনটি শুধুমাত্র x প্ল্যান উপস্থাপন করতে পারে এবং প্রতিক্রিয়াটিতে y > x প্ল্যান থাকে শুধুমাত্র প্রথম x প্ল্যান উপস্থাপন করা হবে। GTAF শুধুমাত্র 50টি প্ল্যান শেয়ার করে যদি অফারগুলির জন্য আবেদনকারী মোবাইল ডেটা প্ল্যান মডিউল হয় যা Google Play পরিষেবাগুলির অংশ৷ এটি Google Play পরিষেবার ব্যবহারকারীদের জন্য ভাল ব্যবহারকারীর অভিজ্ঞতা নিশ্চিত করার জন্য।

আপসেল অফারগুলিতে একটি ঐচ্ছিক প্যারামিটার হিসাবে ফিল্টারট্যাগ রয়েছে যা প্রতিটি পরিকল্পনার সাথে সংযুক্ত ট্যাগগুলির একটি অ্যারে। এই সমস্ত ফিল্টারট্যাগগুলি ট্যাগের সাথে মেলে যা ফিল্টারের ভিতরে একটি বস্তু। Filter হল একটি প্রথম স্তরের বস্তু যা tuple ধারণ করে . Filter হল ফিল্টারগুলির একটি সমন্বিত তালিকা যা UI এ রেন্ডার করা হবে৷ ডিসপ্লেটেক্সটে ক্লিক করে ব্যবহারকারী ফিল্টার করতে পারে। ডিসপ্লেটেক্সটের সাথে সম্পর্কিত ট্যাগটি অফারগুলি ফিল্টার করতে ব্যবহৃত হয়।

নোট করুন যে ব্যবহারকারীর কাছে প্রসারিত যেকোন অফারের জন্য একটি ক্রয়ের অনুরোধ পূরণ করার জন্য অপারেটরের অবশ্যই একটি ব্যবস্থা থাকতে হবে। যে প্রক্রিয়ার মাধ্যমে ব্যবহারকারীকে যেকোনো ক্রয়ের জন্য চার্জ করা হবে তা উত্তরে ফর্মঅফপেমেন্ট বিকল্প ব্যবহার করে GTAF এর সাথে যোগাযোগ করা যেতে পারে।

ডেটা ক্রয়

ক্রয় পরিকল্পনা API সংজ্ঞায়িত করে কিভাবে GTAF DPA এর মাধ্যমে প্ল্যান ক্রয় করতে পারে। GTAF DPA-তে একটি ডেটা প্ল্যান কেনার জন্য লেনদেন শুরু করে। অনুরোধের মধ্যে একটি অনন্য লেনদেন শনাক্তকারী (ট্রানজ্যাকশনআইডি) অন্তর্ভুক্ত থাকবে যাতে অনুরোধগুলি ট্রেস করা যায় এবং ডুপ্লিকেট লেনদেন সম্পাদন এড়ানো যায়। DPA অবশ্যই সফল/ব্যর্থতার প্রতিক্রিয়া সহ প্রতিক্রিয়া জানাবে।

লেনদেনের অনুরোধ

একবার এটি একটি ক্লায়েন্টের কাছ থেকে একটি অনুরোধ গ্রহণ করলে, GTAF DPA-কে একটি 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.
}

লেনদেন প্রতিক্রিয়া

DPA শুধুমাত্র সফলভাবে সম্পাদিত লেনদেন বা সারিবদ্ধ লেনদেনের জন্য 200-ওকে প্রতিক্রিয়া তৈরি করবে। ত্রুটির ক্ষেত্রে প্রত্যাশিত প্রতিক্রিয়ার জন্য দয়া করে ত্রুটির কেসগুলি দেখুন৷ সারিবদ্ধ লেনদেনের ক্ষেত্রে DPA শুধুমাত্র লেনদেনের স্থিতি পূরণ করবে এবং প্রতিক্রিয়ার অন্যান্য ক্ষেত্রগুলি খালি রাখবে। একবার সারিবদ্ধ লেনদেন পরিচালনা করা হলে DPA অবশ্যই একটি প্রতিক্রিয়া সহ GTAF কে কল করতে হবে। প্রতিক্রিয়ার মূল অংশটি লেনদেন প্রতিক্রিয়ার একটি উদাহরণ যার মধ্যে নিম্নলিখিত বিবরণ রয়েছে:

{
  "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 অনুমান করবে যে প্ল্যানটি সক্রিয় করা হয়েছে।

CPID নিবন্ধন করুন

যখন কোনো ক্লায়েন্ট যেটি বিজ্ঞপ্তি সমর্থন করে সে যখন CPID এন্ডপয়েন্ট থেকে একটি নতুন CPID পায়, ক্লায়েন্ট শর্তাবলী GTAF কে তা করার অনুমতি দিলে এটি GTAF-এর সাথে CPID নিবন্ধন করে। যদি ক্লায়েন্ট GTAF এর সাথে সফলভাবে CPID নিবন্ধন করে, তাহলে GTAF নিম্নলিখিত API কল ব্যবহার করে DPA-এর সাথে CPID নিবন্ধন করবে:

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

যেখানে userKey হল CPID এবং একমাত্র CLIENT_ID সমর্থিত হল মোবাইলডেটাপ্ল্যান । অনুরোধের মূল অংশটি RegisterCpidRequest- এর একটি উদাহরণ এবং এতে সেই সময় রয়েছে যার পরে CPID বিজ্ঞপ্তি পাঠানোর জন্য ব্যবহার করা যাবে না এবং এটির মত দেখাচ্ছে:

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

এই APIটি শুধুমাত্র অপারেটরদের জন্য প্রাসঙ্গিক যারা Google Play পরিষেবাগুলিতে মোবাইল ডেটা প্ল্যান মডিউল সমর্থন করতে চান৷ ব্যবহারকারীকে নির্ভরযোগ্যভাবে বিজ্ঞপ্তি পাঠানোর জন্য, DPA প্রতিটি ব্যবহারকারীর জন্য সর্বশেষ নিবন্ধিত CPID সংরক্ষণ করতে পারে। বিজ্ঞপ্তি পাঠানোর জন্য কিভাবে নিবন্ধিত CPID ব্যবহার করতে হয় তার নির্দেশনার জন্য অনুগ্রহ করে CPID নির্বাচন করা দেখুন।

যদি DPA সফলভাবে ব্যবহারকারীর সাথে CPID যুক্ত করে এবং ক্রমাগতভাবে সংরক্ষণ করে তাহলে DPA একটি 200-ওকে প্রতিক্রিয়া তৈরি করবে। ত্রুটির ক্ষেত্রে প্রত্যাশিত প্রতিক্রিয়ার জন্য দয়া করে ত্রুটির কেসগুলি দেখুন৷

সম্মতি

GTAF ব্যবহারকারীর সম্মতি অগ্রাধিকার ক্যারিয়ারে পাস করার জন্য নিম্নলিখিত অনুরোধ জারি করতে পারে।

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

যেখানে userKey হয় একটি CPID বা MSISDN । অনুরোধের মূল অংশটি SetConsentStatusRequest এর একটি উদাহরণ। সফল হলে, প্রতিক্রিয়া বডি খালি হওয়া উচিত।

GTAF থেকে DPA-তে প্রতিটি কল Google ক্লায়েন্টের কল করার পরিষেবার শর্তাবলী অনুসরণ করে। ডিপিএ যে অ্যাপ্লিকেশনগুলিকে সমর্থন করতে চাইছে তার উপর নির্ভর করে, ডিপিএ এই APIটি প্রয়োগ করে কিনা তা অপারেটরের উপর নির্ভর করে। যদি DPA সম্মতি API প্রয়োগ করতে বেছে নেয়, DPA-কে অবশ্যই প্রতিটি ব্যবহারকারীর জন্য সর্বশেষ সম্মতির স্থিতি সংরক্ষণ করতে হবে। সম্মতি স্থিতির তথ্য কীভাবে ব্যবহার করবেন সে সম্পর্কে নির্দেশনার জন্য অনুগ্রহ করে CPID নির্বাচন করা দেখুন।

সাফল্যের ক্ষেত্রে, ডিপিএকে অবশ্যই একটি খালি প্রতিক্রিয়া বডি সহ HTTP 200 OK ফেরত দিতে হবে। ত্রুটির ক্ষেত্রে প্রত্যাশিত প্রতিক্রিয়ার জন্য দয়া করে ত্রুটির কেসগুলি দেখুন৷