Motivasyon
Genel bakış bölümünde belirtildiği gibi, operatörün desteklemek istediği kullanım alanlarına bağlı olarak DPA'nın Google Mobil Veri Planı Paylaşımı API'si ile Veri Planı Aracı API'sinin bir kombinasyonunu uygulaması gerekir. Bu belgede, Google'ın kullanıcının mobil veri planlarını belirlemek, bu planlarla ilgili bilgileri almak ve veri planları satın almak için kullanacağı Data Plan Agent API açıklanmaktadır.
Kimlik doğrulama
GTAF arama yapmadan önce DPA, GTAF'yi doğrulamalıdır. Operatörün ilk katılım süreci kapsamında, DPA SSL sertifikasının geçerliliği kontrol edilir. Şu anda karşılıklı kimlik doğrulama için OAuth2 KULLANIMI ZORUNLUDUR. GTAF'nin DPA ile kimliğini doğrulama şekli hakkında ayrıntılı bilgi için lütfen Data Plan Agent Authentication (Veri Planı Aracı Kimlik Doğrulaması) başlıklı makaleyi inceleyin.
Uluslararası hale getirme
DPA'ya yapılan GTAF istekleri, okunabilir dizelerin (ör. plan açıklamaları) hangi dilde olması gerektiğini belirten bir Accept-Language başlığı içerir. Ayrıca, DPA yanıtları (PlanStatus, PlanOffers), değeri BCP-47 dil kodu olan (ör. "en-US") of the response.
DPA, kullanıcının istediği dili desteklemiyorsa varsayılan bir dil kullanabilir ve LanguageCode alanını kullanarak seçimini belirtebilir.
API Açıklaması
GTAF, operatörün DPA'sını sorgularken operatöre abone olan bir kullanıcıyı tanımlayan kullanıcı anahtarını kullanır. GTAF, MSISDN'ye erişimi olan uygulamalar adına DPA'ya sorgu gönderirken MSISDN'yi KULLANABİLİR. Özet olarak, önerilen Veri Planı Aracısı API'si aşağıdaki bileşenlerden oluşur:
- Kullanıcı verileri planı durumunu sorgulama mekanizması.
- Kullanıcıya yönelik veri planı teklifleri için DPA'yı sorgulama mekanizması.
- Kullanıcının veri planında değişiklik yapma mekanizması (ör. yeni bir plan satın alma).
- Kullanıcılara bildirim göndermek için kullanılabilecek CPID'leri paylaşma mekanizması.
- Kullanıcıların hizmetimize kaydolma tercihlerini paylaşma mekanizması.
Bu belgenin kalanında, söz konusu API bileşenlerinin her biri ayrıntılı olarak açıklanmaktadır. Aksi açıkça belirtilmediği sürece tüm iletişimler HTTPS üzerinden (geçerli bir DPA SSL sertifikasıyla) yapılmalıdır. Desteklenen özelliklere bağlı olarak bir operatör, bu API bileşenlerinin tümünü veya bir alt kümesini uygulamayı SEÇEBİLİR.
GTAF-DPA Etkileşimi
Şekil 4. Kullanıcı verileri planı bilgilerini isteme ve alma için çağrı akışı.
Şekil 4, kullanıcının veri planı durumu ve diğer veri planı bilgileri hakkında sorgu gönderdiği sırada gerçekleşen arama akışını gösterir. Bu çağrı akışı, UE'de istemci tarafından tetiklenen API çağrıları için paylaşılır.
- İstemci, özel bir Google API'sini çağırarak veri planı durumu ve/veya diğer bilgileri ister. İstemci, GTAF'ye gönderdiği isteğe kullanıcı anahtarını ekler.
- GTAF, operatörün DPA'sını sorgulamak için kullanıcı anahtarını ve bir istemci tanımlayıcısını kullanır. Desteklenen istemci tanımlayıcıları mobiledataplan ve youtube'dur. DPA, bu istemci tanımlayıcılarından birini içeren bir arama aldığında istemcinin kullanabileceği plan bilgileriyle yanıt VERMELİDİR.
- GTAF, istenen bilgileri istemciye döndürür ve plan bilgileri, DPA tarafından belirtilen son kullanma süresine kadar GTAF tarafından önbelleğe alınır.
Şekil 4'teki 1. ve 3. adımlar özel Google API'leridir ve bu nedenle daha ayrıntılı açıklanmamıştır. 2. adım, aşağıda açıklanan herkese açık bir API'dir. DPA, GTAF'den gelen bu API çağrılarını sunarken Cache-Control: no-cache HTTP üst bilgisine UYMALIDIR.
Veri Planı Durumunu Sorgulama
GTAF, plan durumunu almak için aşağıdaki HTTP isteğini gönderir:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
GTAF'nin DPA ile iletişime geçtiği müşteri, CLIENT_ID kullanılarak tanımlanır. Google istemcisi ile operatör arasındaki sözleşmeye bağlı olarak, DPA, GTAF'ye verilen yanıtı özelleştirebilir. Başarı durumunda DPA, PlanStatus'u temsil eden bir yanıt gövdesiyle HTTP 200 OK döndürmelidir. Hatalar durumunda beklenen yanıt için lütfen Hata Durumları bölümüne bakın.
{
"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
}
}
}
}
Faturalı planlarda expirationTime, planın yinelenme tarihi OLMALIDIR (ör. veri bakiyesinin yenilendiği/yeniden yüklendiği zaman).
Her plan modülü birden fazla Plan Modülü Trafik Kategorisi (PMTCs)) içerebilir.Bu, bir plan modülünün birden fazla uygulama arasında paylaşıldığı durumu modellemek için kullanılır (ör. 500 MB (oyun ve müzik için). Aşağıdaki PMTC'ler önceden tanımlanmıştır: GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Operatörlerin, farklı Google uygulamaları için geçerli olan trafik kategorileri ve bunların semantiği konusunda anlaşmak üzere Google'ın ilgili ekipleriyle iletişime geçmesi beklenir.
Plan tekliflerini sorgulama
GTAF, operatörden plan teklifleri almak için aşağıdaki HTTP isteğini gönderir:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
GTAF'nin DPA ile iletişime geçtiği müşteri, CLIENT_ID kullanılarak tanımlanır. Google istemcisi ile operatör arasındaki sözleşmeye bağlı olarak, DPA, GTAF'ye verilen yanıtı özelleştirebilir. İsteğe bağlı bağlam parametresi, isteğin yapıldığı uygulama bağlamını sağlar. Bu genellikle uygulamanın GTAF aracılığıyla operatöre ilettiği bir dizedir.
Başarılı olursa DPA, PlanOffer'ı temsil eden bir yanıt gövdesiyle birlikte HTTP 200 OK döndürmelidir. Hata durumunda beklenen yanıt için lütfen Hata Durumları'na bakın.
{
"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 dizisindeki veri planlarının sırası, kullanıcılara sunulacak veri planlarının sırasını belirleyebilir. Ayrıca, uygulama kullanıcı arayüzü veya diğer sınırlamalar nedeniyle yalnızca x plan sunabiliyorsa ve yanıtta yalnızca y > x plan varsa yalnızca ilk x plan sunulmalıdır. GTAF, teklif sorgulayan uygulama Google Play Hizmetleri'nin bir parçası olan Mobil Veri Planı modülü ise yalnızca 50 plana kadar paylaşım yapar. Bu, Google Play Hizmetleri kullanıcılarına iyi bir kullanıcı deneyimi sunmak için yapılır.
Ek satış tekliflerinde, her plana eklenen etiket dizisi olan isteğe bağlı bir parametre olarak filterTags bulunur. Bu filterTags'lerin tümü, Filter içindeki bir nesne olan etiketle eşleşmelidir. Filter, tuple<tag, displaytext=""> içeren birinci düzey bir nesnedir. Filter, kullanıcı arayüzünde oluşturulacak filtrelerin birleştirilmiş listesidir. Kullanıcı, DisplayText'i tıklayarak filtreleme yapabilir. displayText'e karşılık gelen etiket, teklifleri filtrelemek için kullanılır.</tag,>
Operatörün, kullanıcıya sunulan tüm teklifler için satın alma isteğini karşılayacak bir mekanizmaya sahip olması GEREKİR. Kullanıcının satın alma işlemleri için ücretlendirileceği mekanizma, yanıttaki formOfPayment seçeneği kullanılarak GTAF ile paylaşılabilir.
Veri Satın Alma
Satın alma planı API'si, GTAF'nin DPA aracılığıyla planları nasıl satın alabileceğini tanımlar. GTAF, DPA'dan bir veri planı satın alma işlemini başlatır. İstek, istekleri izlemek ve yinelenen işlem yürütülmesini önlemek için benzersiz bir işlem tanımlayıcısı (transactionId) İÇERMELİDİR. DPA, başarı/başarısızlık yanıtı VERMELİDİR.
İşlem İsteği
GTAF, bir istemciden istek aldığında DPA'ya bir POST isteği gönderir. İsteğin URL'si:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
burada userKey, CPID veya MSISDN'dir. İsteğin gövdesi, aşağıdaki alanları içeren bir TransactionRequest örneğidir:
{
"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.
}
İşlem Yanıtı
DPA, yalnızca başarıyla yürütülen bir işlem veya sıraya alınmış bir işlem için 200-OK yanıtı ÜRETİR. Hata durumunda beklenen yanıt için lütfen Hata Durumları bölümüne bakın. Sıraya alınmış bir işlem söz konusu olduğunda, DPA yalnızca işlem durumunu dolduracak ve yanıttaki diğer alanları boş bırakacaktır. Bir sıraya alınmış işlem işlendikten sonra DPA, GTAF'yi yanıtla birlikte geri aramalıdır. Yanıtın gövdesi, aşağıdaki ayrıntıları içeren bir TransactionResponse örneğidir:
{
"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 eksikse GTAF, planın etkinleştirildiğini VARSAYAR.
CPID'yi kaydetme
Bildirimleri destekleyen bir istemci, CPID uç noktasından yeni bir CPID aldığında, istemci şartları GTAF'nin bunu yapmasına izin veriyorsa CPID'yi GTAF'ye kaydeder. İstemci, CPID'yi GTAF'ye başarıyla kaydederse GTAF, aşağıdaki API çağrısını kullanarak CPID'yi DPA'ya kaydeder:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Burada userKey, CPID'dir ve desteklenen tek CLIENT_ID, mobiledataplan'dır. İsteğin gövdesi, RegisterCpidRequest örneğidir ve CPID'nin bildirim göndermek için kullanılamayacağı zamanı içerir. Bu zaman şu şekilde görünür:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
Bu API yalnızca Google Play Hizmetleri'nde Mobil Veri Planı modülünü desteklemek isteyen operatörler için geçerlidir. DPA, kullanıcılara güvenilir bir şekilde bildirim göndermek için her kullanıcının en son kayıtlı CPID'sini saklayabilir. Bildirim göndermek için kayıtlı CPID'nin nasıl kullanılacağıyla ilgili yönergeler için lütfen CPID seçme başlıklı makaleyi inceleyin.
Veri işleme sözleşmesi, CPID'yi kullanıcıyla başarıyla ilişkilendirir ve kalıcı olarak saklarsa 200-OK yanıtı oluşturur. Hata durumunda beklenen yanıt için lütfen Hata Durumları'na bakın.
İzin
GTAF, kullanıcı rızası tercihini operatöre iletmek için aşağıdaki isteği gönderebilir.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
burada userKey, CPID veya MSISDN'dir. İsteğin gövdesi, SetConsentStatusRequest örneğidir. Başarılı olursa yanıt metni boş olmalıdır.
GTAF'nin DPA'ya yaptığı her çağrı, Google istemcisinin hizmet şartlarına tabidir. DPA'nın desteklemek istediği uygulamalara bağlı olarak, bu API'nin DPA tarafından uygulanıp uygulanmayacağına operatör karar verir. Veri işleyen, izin API'sini uygulamayı seçerse her kullanıcının en son izin durumunu sakLAMALIDIR. İzin durumu bilgilerini nasıl kullanacağınızla ilgili yönergeler için lütfen CPID Seçme başlıklı makaleyi inceleyin.
Başarı durumunda, DPA, boş yanıt gövdesiyle HTTP 200 OK döndürmelidir. Hatalar durumunda beklenen yanıt için lütfen Hata Durumları'nı inceleyin.