Motivasyon
Genel bakışta belirtildiği gibi, operatörün desteklemek istediği kullanım alanlarına bağlı olarak DPA, Google Mobil Veri Planı Paylaşım API'si ile Veri Planı Aracı API'sinin bir kombinasyonunu uygulamalıdır. Bu dokümanda, Google'ın kullanıcının mobil veri planlarını tanımlamak, bu planlarla ilgili bilgileri almak ve veri planlarını satın almak için kullanacağı Data Plan Agent API'si açıklanmaktadır.
Kimlik doğrulama
GTAF'nin arama yapabilmesi için DPA'nın GTAF'nın kimliğini doğrulaması gerekir. Operatör ilk katılım süreci kapsamında DPA SSL sertifikasının geçerliliğini kontrol edeceğiz. Şu anda karşılıklı kimlik doğrulama için OAuth2 kullanımı GEREKİYOR. GTAF'ın DPA ile kimliğini nasıl doğruladığını öğrenmek için lütfen Veri Planı Aracı Kimlik Doğrulaması bölümüne bakın.
Uluslararası hale getirme
DPA'ya gönderilen GTAF istekleri, insanların okuyabileceği dizelerin (ör. plan açıklamaları) olması gereken dili belirten bir Accept-Language üstbilgisi içerir. Ayrıca DPA yanıtları (PlanStatus, PlanOffers) değeri BCP-47 dil kodu (ör. yanıt verin.
DPA, kullanıcının istediği dili desteklemiyorsa varsayılan bir dil kullanıp seçimini belirtmek için LanguageCode alanını kullanabilir.
API Açıklaması
GTAF, operatör DPA'sını sorgularken operatörün abonesini tanımlayan kullanıcı anahtarını kullanır. GTAF, MSISDN'ye erişimi olan uygulamalar adına DPA'yı sorgularken GTAF, MSISDN'yi kullanabilir. Genel olarak, önerilen Data Plan Agent API'si aşağıdaki bileşenleri içerir:
- Kullanıcı veri planı durumunu sorgulama mekanizması.
- 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ı.
- Hizmetimize kaydolup kaydolmayacağınızla ilgili kullanıcı seçimlerini paylaşma mekanizması.
Bu dokümanın geri kalanında, bu API bileşenlerinin her biri ayrıntılı olarak açıklanmaktadır. Açıkça belirtilmediği sürece tüm iletişimlerin HTTPS üzerinden (geçerli bir DPA SSL sertifikasıyla) gerçekleşmesi ZORUNLUDUR. Desteklenen gerçek özelliklere bağlı olarak, bir operatör bu API bileşenlerinin tamamını veya bir alt kümesini uygulamayı SEÇEBİLİR.
GTAF-DPA Etkileşimi
4. Şekil. Kullanıcı veri planı bilgilerini istemek ve almak için arama akışı.
4. şekilde, kullanıcının veri planı durumu ve diğer veri planı bilgileriyle ilgili sorgu yapan bir istemciyle ilişkilendirilen çağrı akışı gösterilmektedir. Bu çağrı akışı, istemcinin UE'de tetiklediği API çağrıları için paylaşılır.
- İstemci, özel bir Google API'yi çağırarak veri planı durumunu ve/veya diğer bilgileri ister. İstemci, GTAF isteğine kullanıcı anahtarını ekler.
- GTAF, operatör DPA'sını sorgulamak için kullanıcı anahtarını ve 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 biriyle arama aldığında istemci tarafından kullanılabilecek plan bilgilerine yanıt vermelidir.
- GTAF, istenen bilgileri istemciye döndürür ve plan bilgileri, DPA tarafından belirlenen geçerlilik bitiş zamanına kadar GTAF tarafından önbelleğe alınır.
Şekil 4'teki 1. ve 3. adım, özel Google API'leridir ve bu nedenle daha ayrıntılı olarak açıklanmamıştır. 2. adım, aşağıda açıklandığı şekilde herkese açık bir API'dir. DPA, GTAF'den bu API çağrılarını yayınlarken Cache-Control: no-cache HTTP üst bilgisine uymalıdır.
Veri Planı Durumunu Sorgulama
GTAF, plan durumunu almak için aşağıdaki HTTP isteğini yayınlar:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
GTAF'nın DPA ile iletişim kurduğu müşteri, CLIENT_ID kullanılarak tanımlanır. DPA, Google istemcisi ile operatör arasındaki sözleşmeye bağlı olarak GTAF'ya verilen yanıtı özelleştirebilir. Başarılı olursa DPA, PlanStat'u temsil eden bir yanıt gövdesine sahip, HTTP 200 OK'yi döndürmelidir. Hatalarla karşılaşmanız durumunda beklenen yanıt için lütfen Hata Örnekleri'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ı ödemeler için expirationTime, planın yinelenme tarihi (ZORUNLU veri bakiyesinin yenilendiği/yeniden yüklendiği) olmalıdır.
Her plan modülünde birden fazla Plan Modülü Trafik Kategorisi (PMTCs)bir plan modülünün birden fazla uygulama (ör. oyun ve müzik için 500 MB). 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ı ile ilgili trafik kategorileri ve anlamları konusunda anlaşmak üzere her bir Google ekibiyle iletişime geçmesi beklenir.
Plan Tekliflerini Sorgulama
GTAF, operatörden plan teklifleri almak için aşağıdaki HTTP isteğini yayınlar:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
GTAF'nın DPA ile iletişim kurduğu müşteri, CLIENT_ID kullanılarak tanımlanır. DPA, Google istemcisi ile operatör arasındaki sözleşmeye bağlı olarak GTAF'ya verilen yanıtı özelleştirebilir. İsteğe bağlı bağlam parametresi, isteğin yapıldığı uygulama bağlamını sağlar. Genellikle bu, uygulamanın GTAF üzerinden operatöre aktardığı bir dizedir.
Başarılı olursa DPA, PlanOffer'ı temsil eden bir yanıt gövdesine sahip HTTP 200 OK döndürmelidir. Hata durumunda beklenen yanıt için lütfen Hata Durumları'nı inceleyin.
{
"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ı, veri planlarının kullanıcılara sunulma sırasını BELİRTİR. Ayrıca, uygulama kullanıcı arayüzü veya diğer sınırlamalar nedeniyle yalnızca x planlarını sergileyebiliyorsa ve yanıtta y > x planları yer alıyorsa yalnızca ilk x planları sunulur. GTAF, teklifleri sorgulamak için Google Play Hizmetleri'nin bir parçası olan Mobil Veri Planı modülünü kullanıyorsa en fazla 50 plan paylaşır. Bunun amacı, Google Play Hizmetleri kullanıcılarına iyi bir kullanıcı deneyimi sunmaktır.
Ek satış teklifleri, her plana ekli bir etiket dizisi olan isteğe bağlı parametre olarak filterTag'lere sahiptir. Bu filtre filtrelerinin tümü, Filtre içindeki bir nesne olan etiketle eşleşmelidir. Filter Tup<tag, displaytext=""> ifadesini içeren birinci düzey bir nesnedir. Filter, kullanıcı arayüzünde oluşturulacak filtrelerin birleştirilmiş bir listesidir. Kullanıcı, DisplayText öğesini tıklayarak filtre uygulayabilir. displayText'e karşılık gelen etiket, teklifleri filtrelemek için kullanılır.</tag,>
Operatörün, kullanıcıya sunulan tüm fırsatlar için bir satın alma isteğini yerine getirecek bir mekanizmaya sahip olması ZORUNLUDUR. Kullanıcıdan tüm satın alma işlemleri için ödeme alınacak mekanizma, yanıttaki formOfPayment seçeneği kullanılarak GTAF ile iletişim kurabilir.
Veri Satın Alma
Satın alma planı API'si, GTAF'nın DPA aracılığıyla planları nasıl satın alabileceğini tanımlar. GTAF, DPA'ya bir veri planı satın almak için işlemi başlatır. İstek, istekleri izlemek ve yinelenen işlem yürütmeyi önlemek için benzersiz bir işlem tanımlayıcısı (transactionId) içermelidir. DPA'nın başarılı/başarısız bir yanıtla yanıt vermesi ZORUNLUDUR.
İşlem İsteği
GTAF, istemciden istek aldıktan sonra 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 gerçekleştirilen bir işlem veya sıraya alınmış bir işlem için 200 OK yanıtını üretir. Hata durumunda beklenen yanıt için lütfen Hata Örnekleri'ne bakın. Sıraya alınmış bir işlem söz konusuysa DPA yalnızca işlem durumunu doldurur ve yanıttaki diğer alanları boş bırakır. Sıraya alınmış bir işlem gerçekleştirildiğinde DPA'nın GTAF'yı geri çağırması GEREKİR. Yanıt 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 kaydedin
Bildirimleri destekleyen bir istemci, CPID uç noktasından yeni bir CPID aldığında, istemci şartları GTAF'nin izni veriyorsa CPID'yi GTAF'ya kaydeder. İstemci CPID'yi GTAF'ya başarıyla kaydederse GTAF, aşağıdaki API çağrısını kullanarak CPPA'yı DPA'ya kaydeder:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Burada CPID userKey, desteklenen tek CLIENT_ID ise mobiledataplan şeklindedir. İsteğin gövdesi, EnrollmentCpidRequest öğesinin bir örneğidir ve CPID'nin bildirim göndermek için kullanılamayacağı süreyi içerir ve aşağıdaki gibi 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. Kullanıcıya güvenilir bir şekilde bildirim göndermek için DPA, her kullanıcının en son kayıtlı CPID'sini depolayabilir. Bildirim göndermek için kayıtlı CPID'yi nasıl kullanacağınıza dair yönergeler için lütfen CPID'yi seçme bölümüne bakın.
DPA, SQLID'yi kullanıcı ile başarılı bir şekilde ilişkilendirir ve kalıcı olarak depolarsa 200 OK yanıtı oluşturur. Hata durumunda beklenen yanıt için lütfen Hata Durumları'nı inceleyin.
İzin
GTAF, kullanıcı rızası tercihini operatöre iletmek için aşağıdaki isteği verebilir.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
burada userKey, CPID veya MSISDN'dir. İsteğin gövdesi, SetConsentStatusRequest öğesinin bir örneğidir. Başarılı olursa yanıt gövdesi boş olmalıdır.
GTAF'den DPA'ya yapılan her arama, aramayı yapan Google müşterisinin hizmet şartlarına uyar. DPA'nın desteklemek istediği uygulamalara bağlı olarak, DPA'nın bu API'yi uygulayıp uygulamayacağına operatör karar verir. DPA, izin API'sini uygulamayı seçerse DPA, her kullanıcı için en son izin durumunu saklamalıdır. İzin durumu bilgilerinin nasıl kullanılacağıyla ilgili yönergeler için lütfen CPID'yi seçme bölümüne bakın.
Başarılı olursa DPA, boş bir yanıt gövdesiyle HTTP 200 OK döndürmelidir. Hata durumunda beklenen yanıt için lütfen Hata Durumları'nı inceleyin.