वजह
जैसा कि खास जानकारी में बताया गया है, अहमियत के हिसाब से ऑपरेटर काम करना चाहता है. इसलिए, डीपीए को Google मोबाइल डेटा प्लान शेयर करने वाले एपीआई और डेटा प्लान एजेंट एपीआई के कॉम्बिनेशन को लागू करना होगा. इस दस्तावेज़ में उस डेटा प्लान एजेंट एपीआई के बारे में बताया गया है जिसका इस्तेमाल Google, उपयोगकर्ता के मोबाइल डेटा प्लान की पहचान करने, इन प्लान के बारे में जानकारी पाने, और डेटा प्लान खरीदने के लिए करेगा.
पुष्टि करना
GTAF के कॉल करने से पहले, डीपीए को GTAF की पुष्टि करनी होगी. ऑपरेटर ऑनबोर्डिंग की प्रोसेस के दौरान, हम जांच करेंगे कि डीपीए एसएसएल सर्टिफ़िकेट मान्य है या नहीं. फ़िलहाल, हम मान्य पुष्टि करने के लिए OAuth2 का इस्तेमाल करना चाहते हैं. GTA ने डीपीए की मदद से खुद की पुष्टि कैसे की, इस बारे में जानने के लिए, कृपया डेटा प्लान एजेंट की पुष्टि देखें.
अंतर्राष्ट्रीयकरण
डीपीए के लिए डीपीए के अनुरोधों में, 'भाषा का स्वीकार करें' हेडर शामिल होता है. इससे यह पता चलता है कि उपयोगकर्ता की पढ़ी जा सकने वाली स्ट्रिंग (उदाहरण के लिए, प्लान की जानकारी) में क्या होना चाहिए. इसके अलावा, डीपीए के रिस्पॉन्स (प्लान की स्थिति, PlanOffers) में एक ज़रूरी लैंग्वेज कोड फ़ील्ड होता है. इसकी वैल्यू BCP-47 भाषा कोड (उदाहरण के लिए, जवाब के "en-US").
अगर डीपीए उपयोगकर्ता की अनुरोध की गई भाषा में काम नहीं करता है, तो वह डिफ़ॉल्ट भाषा का इस्तेमाल कर सकता है और अपनी पसंद को दिखाने के लिए लैंग्वेज कोड फ़ील्ड का इस्तेमाल कर सकता है.
एपीआई की जानकारी
GTAF, उपयोगकर्ता कुंजी का इस्तेमाल करता है, जो ऑपरेटर के डीपीए के बारे में क्वेरी करते समय ऑपरेटर को बताता है कि वह सदस्य है या नहीं. जब GTAF, MSISDN को ऐक्सेस करने वाले ऐप्लिकेशन की ओर से डीपीए की क्वेरी करता है, तो GTAF, MSISDN का इस्तेमाल करता है. हाई लेवल पर, सुझाए गए डेटा प्लान एजेंट एपीआई में ये कॉम्पोनेंट शामिल होते हैं:
- उपयोगकर्ता के डेटा प्लान की स्थिति के बारे में क्वेरी करने का तरीका.
- उपयोगकर्ता के लिए, डेटा प्लान के ऑफ़र (डीपीए) की क्वेरी करने का तरीका.
- उपयोगकर्ता के डेटा प्लान में बदलाव करने का तरीका (उदाहरण के लिए, नया प्लान खरीदना).
- उपयोगकर्ताओं को सूचनाएं भेजने के लिए, सीपीआईडी शेयर करने का तरीका.
- हमारी सेवाओं के लिए साइन अप करने या न करने के बारे में उपयोगकर्ता की पसंद शेयर करने का तरीका.
इस दस्तावेज़ के बाकी हिस्से में, एपीआई से जुड़े हर कॉम्पोनेंट के बारे में जानकारी दी गई है. जब तक साफ़ तौर पर न बताया जाए, तब तक सभी कम्यूनिकेशन एचटीटीपीएस (एक मान्य डीपीए एसएसएल सर्टिफ़िकेट के साथ) पर होने चाहिए. असल में काम की जा सकने वाली सुविधाओं के आधार पर, ऑपरेटर इन एपीआई कॉम्पोनेंट के सभी या कुछ सबसेट को लागू करने का विकल्प चुन सकता है.
GTAF-DPA इंटरैक्शन
चौथी इमेज. उपयोगकर्ता के डेटा प्लान की जानकारी पाने का अनुरोध करने और उसे पाने के लिए, कॉल फ़्लो.
चित्र 4, उपयोगकर्ता के डेटा प्लान की स्थिति और डेटा प्लान की अन्य जानकारी की क्वेरी करने वाले क्लाइंट से जुड़े कॉल फ़्लो को दिखाता है. यह कॉल फ़्लो, क्लाइंट की ओर से UE पर ट्रिगर किए गए एपीआई कॉल के साथ शेयर किया जाता है.
- क्लाइंट, निजी Google API पर कॉल करके डेटा प्लान की स्थिति और/या दूसरी जानकारी का अनुरोध करता है. क्लाइंट ने GTAF के अनुरोध में उपयोगकर्ता कुंजी शामिल की है.
- GTAF, ऑपरेटर और उपयोगकर्ता डीपीए के बारे में क्वेरी करने के लिए, उपयोगकर्ता कुंजी और क्लाइंट आइडेंटिफ़ायर का इस्तेमाल करता है. mobiledataplan और youtube, क्लाइंट आईडी की सुविधा देते हैं. जब डीपीए को इनमें से किसी एक क्लाइंट आइडेंटिफ़ायर का कॉल मिलता है, तो उसे प्लान की जानकारी का जवाब देना ज़रूरी है. इस जानकारी का इस्तेमाल क्लाइंट कर सकता है.
- GTAF, क्लाइंट को अनुरोध की गई जानकारी दिखाता है और प्लान की जानकारी को GTAF ने कैश मेमोरी में सेव करने की समयसीमा खत्म होने तक, कैश मेमोरी में सेव किया है.
इमेज 4 में दिए गए पहले और तीसरे चरण, निजी Google API हैं और इसलिए इनके बारे में आगे नहीं बताया गया है. दूसरे चरण में बताया गया सार्वजनिक एपीआई है. डीपीए को
GTAF से ये एपीआई कॉल दिखाते समय, Cache-Control: no-cache एचटीटीपी हेडर का सम्मान करना चाहिए.
क्वेरी किए जा रहे डेटा प्लान का स्टेटस
GTAF, प्लान की स्थिति जानने के लिए यह एचटीटीपी अनुरोध जारी करता है:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
GTAF, जिस क्लाइंट की ओर से डीपीए से संपर्क कर रहा है उसकी पहचान CLIENT_ID का इस्तेमाल करके की गई है. Google क्लाइंट और ऑपरेटर के बीच समझौते के आधार पर, डीपीए Google के रिस्पॉन्स को पसंद के मुताबिक बना सकता है. सफलता के मामले में, डीपीए को PlanStatus दिखाने वाले रिस्पॉन्स बॉडी के साथ, एचटीटीपी 200 OK का रिटर्न भरना होगा. गड़बड़ियों के मामले में जवाब पाने के लिए, कृपया गड़बड़ी के मामले देखें.
{
"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, ऑपरेटर से ये प्लान पाने के लिए एचटीटीपी अनुरोध जारी करता है:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
GTAF, जिस क्लाइंट की ओर से डीपीए से संपर्क कर रहा है उसकी पहचान CLIENT_ID का इस्तेमाल करके की गई है. Google क्लाइंट और ऑपरेटर के बीच समझौते के आधार पर, डीपीए Google के रिस्पॉन्स को पसंद के मुताबिक बना सकता है. वैकल्पिक प्रसंग पैरामीटर, ऐप्लिकेशन का वह संदर्भ देता है जिसमें अनुरोध किया गया है. आम तौर पर, यह एक ऐसी स्ट्रिंग होती है जिसे ऐप्लिकेशन, GTAF के ज़रिए ऑपरेटर को भेजता है.
सही होने पर, डीपीए को PlanOffer के रिस्पॉन्स के तौर पर, एचटीटीपी 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 कैटगरी में डेटा प्लान के क्रम से, यह तय होता है कि उपयोगकर्ताओं को डेटा प्लान किस क्रम में दिखाया जाता है. इसके अलावा, अगर ऐप्लिकेशन यूज़र इंटरफ़ेस (यूआई) या दूसरी सीमाओं की वजह से सिर्फ़ x प्लान पेश कर सकता है और जवाब में y > x प्लान शामिल है, तो सिर्फ़ पहले x प्लान को प्रज़ेंट करना चाहिए. GTAF सिर्फ़ 50 प्लान तक शेयर करता है. यह ऑफ़र 'मोबाइल डेटा प्लान मॉड्यूल' के लिए होता है, जो Google Play सेवाओं का हिस्सा होता है. इससे यह पक्का किया जाता है कि
Google Play सेवाओं के उपयोगकर्ताओं को बेहतर अनुभव मिले.
अपसेल ऑफ़र में फ़िल्टर टैग, एक वैकल्पिक पैरामीटर के रूप में होते हैं, जो हर प्लान से जुड़े टैग की श्रेणी होती है. ये सभी फ़िल्टर टैग, टैग के अंदर मौजूद ऑब्जेक्ट से मेल खाने चाहिए. Filter पहला लेवल का ऑब्जेक्ट है, जिसमें
tuble<tag, displaytext="">. Filter फ़िल्टर की एक सूची है, जिसे यूज़र इंटरफ़ेस (यूआई) पर रेंडर किया जाएगा. उपयोगकर्ता DisplayText पर क्लिक करके फ़िल्टर कर सकता है. डिसप्ले टेक्स्ट से जुड़े टैग का इस्तेमाल ऑफ़र को फ़िल्टर करने के लिए किया जाता है.</tag,>
ध्यान रखें कि ऑपरेटर को उपयोगकर्ता के पास, किसी भी ऑफ़र के लिए खरीदारी का अनुरोध पूरा करने का एक तरीका होना चाहिए. जवाब देने के लिए, formOfPayment विकल्प का इस्तेमाल करें. इसकी मदद से, किसी भी खरीदारी के लिए उपयोगकर्ता से शुल्क लिया जा सकता है.
डेटा खरीदारी
खरीदारी प्लान एपीआई, डीपीए के ज़रिए प्लान खरीदने का तरीका बताता है. GTAF, डीपीए की मदद से एक डेटा प्लान खरीदने के लिए लेन-देन शुरू करता है. अनुरोध में, अनुरोधों को ट्रेस करने और डुप्लीकेट ट्रांज़ैक्शन को लागू करने से बचने के लिए, एक यूनीक ट्रांज़ैक्शन आइडेंटिफ़ायर (transactionId) शामिल होना चाहिए. डीपीए को सक्सेस/असफल जवाब ज़रूर देना चाहिए.
लेन-देन का अनुरोध
क्लाइंट से अनुरोध मिलने के बाद, GTAF, डीपीए को पोस्ट करने का अनुरोध करता है. अनुरोध का यूआरएल यह है:
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-ठीक जवाब जनरेट होता है. गड़बड़ियों के मामले में, उम्मीद के मुताबिक जवाब पाने के लिए, कृपया गड़बड़ी के मामले देखें. सूची में लेन-देन सूची में शामिल होने पर, डीपीए सिर्फ़ लेन-देन की स्थिति को भर देगा और जवाब में दूसरे फ़ील्ड खाली छोड़ देगा. डीपीए को कॉल खत्म होने के बाद, 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 मौजूद नहीं है, तो GTAF को यह मानकर चलना चाहिए कि प्लान चालू कर दिया गया है.
सीपीआईडी रजिस्टर करें
जब सूचनाओं के साथ काम करने वाले क्लाइंट को CPID से एंडपॉइंट का नया सीपीआईडी मिलता है, तो वह GTAF के साथ CPID रजिस्टर करता है. अगर क्लाइंट, GTAF के साथ CPID रजिस्टर करता है, तो GTAF, एपीआई की मदद से सीपीआईडी रजिस्टर करेगा:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
जहां userKey सीपीआईडी है और सिर्फ़ CLIENT_ID ही mobiledataplan है. इस अनुरोध का मुख्य हिस्सा RegistrationCpidRequest का एक इंस्टेंस है और इसमें वह समय शामिल है, जिसके बाद सीपीआईडी का इस्तेमाल सूचनाएं भेजने के लिए नहीं किया जा सकता. साथ ही, यह ऐसा दिखता है:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
यह एपीआई सिर्फ़ उन ऑपरेटर के लिए काम का है जो Google Play सेवाओं में मोबाइल डेटा प्लान मॉड्यूल की सुविधा देना चाहते हैं. उपयोगकर्ताओं को भरोसेमंद तरीके से सूचनाएं भेजने के लिए, डीपीए ने हर उपयोगकर्ता के लिए रजिस्टर किया गया सबसे नया सीपीआईडी सेव किया है. सूचनाएं भेजने के लिए, रजिस्टर किए गए सीपीआईडी के इस्तेमाल का तरीका जानने के लिए, कृपया सीपीआईडी चुनना देखें.
अगर डीपीए, सीपीडी को उपयोगकर्ता के साथ जोड़ता है और उसे लगातार सेव करता है, तो डीपीए 200-ठीक रिस्पॉन्स जनरेट करेगा. गड़बड़ियों के मामले में, हमें उम्मीद है कि आपको गड़बड़ी के केस दिखेंगे.
सहमति
GTAF ने मोबाइल और इंटरनेट सेवा देने वाली कंपनी को, उपयोगकर्ता की सहमति लेने की प्राथमिकता पास करने का यह अनुरोध जारी किया है.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
जहां userKey, CPID या MSISDN हो. अनुरोध का मुख्य हिस्सा
SetConsentStatusRequest का उदाहरण है. अगर जवाब
मिल गया है, तो जवाब का मुख्य भाग खाली होना चाहिए.
GTAF से डीपीए को किया जाने वाला हर कॉल, Google क्लाइंट की सेवा की शर्तों के मुताबिक होता है. डीपीए, जिन ऐप्लिकेशन का इस्तेमाल करना चाहता है उनके आधार पर, यह तय करना ऑपरेटर पर निर्भर करता है कि डीपीए इस एपीआई को लागू करता है या नहीं. अगर डीपीए सहमति वाले एपीआई को लागू करता है, तो डीपीए को हर उपयोगकर्ता के लिए सहमति की नई स्थिति सेव करनी होगी. सहमति की स्थिति की जानकारी इस्तेमाल करने का तरीका जानने के लिए, कृपया सीपीआईडी चुनना देखें.
सफलता के मामले में, डीपीए को खाली जवाब वाले एचटीटीपी 200 OK का रिटर्न देना होगा. गड़बड़ियों के मामले में, जवाब के तौर पर दिखने के लिए, कृपया गड़बड़ी के मामले देखें.