Động lực
Như đã đề cập trong phần tổng quan, tuỳ thuộc vào các trường hợp sử dụng mà nhà mạng muốn hỗ trợ, DPA phải triển khai kết hợp Google Mobile Data Plan Sharing API và Data Plan Agent API. Tài liệu này mô tả Data Plan Agent API mà Google sẽ dùng để xác định gói dữ liệu di động của người dùng, truy xuất thông tin về các gói này và mua gói dữ liệu.
Xác thực
Trước khi GTAF có thể gọi, DPA phải xác thực GTAF. Trong quy trình tham gia của nhà mạng, chúng tôi sẽ kiểm tra tính hợp lệ của chứng chỉ SSL DPA. Hiện tại, chúng tôi YÊU CẦU bạn sử dụng OAuth2 để xác thực lẫn nhau. Vui lòng xem phần Xác thực tác nhân gói dữ liệu để biết thông tin chi tiết về cách GTAF tự xác thực với DPA.
Quốc tế hoá
Các yêu cầu GTAF gửi đến DPA bao gồm một tiêu đề Accept-Language cho biết ngôn ngữ mà các chuỗi dễ đọc (ví dụ: nội dung mô tả kế hoạch) phải có. Ngoài ra, các phản hồi DPA (PlanStatus, PlanOffers) bao gồm một trường languageCode bắt buộc có giá trị là mã ngôn ngữ BCP-47 (ví dụ: "en-US") của phản hồi.
Nếu DPA không hỗ trợ ngôn ngữ mà người dùng yêu cầu, thì DPA có thể sử dụng ngôn ngữ mặc định và sử dụng trường languageCode để cho biết lựa chọn của mình.
Nội dung mô tả API
GTAF sử dụng khoá người dùng (khoá này xác định một người đăng ký với nhà khai thác) khi truy vấn DPA của nhà khai thác. Khi GTAF truy vấn DPA thay cho các ứng dụng có quyền truy cập vào MSISDN, GTAF CÓ THỂ sử dụng MSISDN. Ở cấp độ cao, Data Plan Agent API được đề xuất bao gồm các thành phần sau:
- Cơ chế truy vấn trạng thái gói dữ liệu của người dùng.
- Cơ chế truy vấn DPA để biết các gói dữ liệu dành cho người dùng.
- Cơ chế để thay đổi gói dữ liệu của người dùng (ví dụ: mua gói mới).
- Cơ chế chia sẻ CPID có thể dùng để gửi thông báo cho người dùng.
- Cơ chế chia sẻ lựa chọn của người dùng về việc có đăng ký dịch vụ của chúng tôi hay không.
Phần còn lại của tài liệu này sẽ trình bày chi tiết về từng thành phần API này. Trừ phi có ghi chú rõ ràng, tất cả hoạt động giao tiếp PHẢI diễn ra qua HTTPS (với chứng chỉ SSL DPA hợp lệ). Tuỳ thuộc vào các tính năng thực tế được hỗ trợ, nhà mạng CÓ THỂ chọn triển khai tất cả hoặc một số thành phần API này.
Tương tác GTAF-DPA
Hình 4. Luồng cuộc gọi để yêu cầu và nhận thông tin gói dữ liệu của người dùng.
Hình 4 minh hoạ quy trình gọi liên quan đến một ứng dụng đang truy vấn về trạng thái gói dữ liệu của người dùng và thông tin khác về gói dữ liệu. Luồng cuộc gọi này được chia sẻ cho các lệnh gọi API do ứng dụng kích hoạt trên UE.
- Ứng dụng khách yêu cầu thông tin về trạng thái gói dữ liệu và/hoặc thông tin khác bằng cách gọi một API riêng tư của Google. Ứng dụng bao gồm khoá người dùng trong yêu cầu gửi đến GTAF.
- GTAF sử dụng khoá người dùng và giá trị nhận dạng ứng dụng để truy vấn DPA của nhà mạng. Giá trị nhận dạng ứng dụng khách được hỗ trợ là mobiledataplan và youtube. Khi nhận được một lệnh gọi có một trong các giá trị nhận dạng ứng dụng này, DPA PHẢI phản hồi bằng thông tin kế hoạch mà ứng dụng có thể sử dụng.
- GTAF trả về thông tin được yêu cầu cho máy khách và thông tin kế hoạch được GTAF lưu vào bộ nhớ đệm cho đến thời gian hết hạn do DPA chỉ định.
Các bước 1 và 3 trong Hình 4 là các API riêng tư của Google và do đó không được mô tả thêm. Bước 2 là một API công khai được mô tả sau đây. DPA PHẢI tuân thủ tiêu đề HTTP Cache-Control: no-cache khi phân phát các lệnh gọi API này từ GTAF.
Truy vấn trạng thái gói dữ liệu
GTAF đưa ra yêu cầu HTTP sau đây để lấy trạng thái kế hoạch:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Ứng dụng thay mặt cho GTAF liên hệ với DPA được xác định bằng CLIENT_ID. Tuỳ thuộc vào thoả thuận giữa máy khách Google và nhà điều hành, DPA có thể tuỳ chỉnh phản hồi cho GTAF. Trong trường hợp thành công, DPA PHẢI trả về HTTP 200 OK cùng với nội dung phản hồi đại diện cho PlanStatus. Vui lòng xem Các trường hợp lỗi để biết phản hồi dự kiến trong trường hợp xảy ra lỗi.
{
"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
}
}
}
}
Đối với gói trả sau, expirationTime PHẢI là ngày lặp lại của gói (tức là khi số dư dữ liệu được làm mới/tải lại).
Mỗi mô-đun kế hoạch có thể chứa nhiều Danh mục lưu lượng truy cập của mô-đun kế hoạch (PMTCs) để mô hình hoá trường hợp một mô-đun kế hoạch được chia sẻ giữa nhiều ứng dụng (ví dụ: 500 MB đối với trò chơi và nhạc). Các PMTC sau đây được xác định trước: GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Các nhà khai thác dự kiến sẽ liên hệ với từng nhóm tại Google để thoả thuận về bộ danh mục lưu lượng truy cập và ngữ nghĩa của các danh mục đó có liên quan đến các ứng dụng khác nhau của Google.
Truy vấn các ưu đãi trong gói
GTAF gửi yêu cầu HTTP sau đây để nhận các ưu đãi về kế hoạch của nhà điều hành:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
Ứng dụng thay mặt cho GTAF liên hệ với DPA được xác định bằng CLIENT_ID. Tuỳ thuộc vào thoả thuận giữa máy khách Google và nhà điều hành, DPA có thể tuỳ chỉnh phản hồi cho GTAF. Tham số ngữ cảnh không bắt buộc cung cấp ngữ cảnh ứng dụng mà yêu cầu được thực hiện. Đây thường là một chuỗi mà ứng dụng truyền đến nhà mạng thông qua GTAF.
Trong trường hợp thành công, DPA PHẢI trả về HTTP 200 OK cùng với một nội dung phản hồi đại diện cho PlanOffer. Vui lòng xem Error Cases (Các trường hợp lỗi) để biết phản hồi dự kiến trong trường hợp xảy ra lỗi.
{
"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.
}
Thứ tự của(các) gói dữ liệu trong mảng offers CÓ THỂ xác định thứ tự mà(các) gói dữ liệu được trình bày cho người dùng. Ngoài ra, nếu ứng dụng chỉ có thể trình bày x gói do giao diện người dùng hoặc các hạn chế khác và phản hồi chỉ chứa y > x gói thì chỉ x gói đầu tiên được trình bày. GTAF chỉ chia sẻ tối đa 50 gói nếu ứng dụng truy vấn các ưu đãi là mô-đun Gói dữ liệu di động, đây là một phần của Dịch vụ Google Play. Điều này nhằm đảm bảo trải nghiệm tốt cho người dùng Dịch vụ Google Play.
Ưu đãi bán thêm có filterTags dưới dạng một tham số không bắt buộc. Đây là một mảng gồm các thẻ được đính kèm vào mỗi gói. Tất cả filterTags này phải khớp với thẻ là một đối tượng bên trong Bộ lọc. Filter là đối tượng cấp đầu tiên chứa bộ dữ liệu<tag, displaytext="">. Filter là danh sách bộ lọc hợp nhất sẽ được kết xuất trên giao diện người dùng. Người dùng có thể lọc bằng cách nhấp vào DisplayText. Thẻ tương ứng với displayText được dùng để lọc các sản phẩm.</tag,>
Xin lưu ý rằng nhà mạng PHẢI có một cơ chế để thực hiện yêu cầu mua đối với mọi ưu đãi được cung cấp cho người dùng. Bạn có thể trao đổi với GTAF về cơ chế mà người dùng sẽ bị tính phí cho mọi giao dịch mua bằng cách sử dụng lựa chọn formOfPayment trong phản hồi.
Mua dữ liệu
API kế hoạch mua hàng xác định cách GTAF có thể mua các kế hoạch thông qua DPA. GTAF bắt đầu giao dịch mua một gói dữ liệu cho DPA. Yêu cầu PHẢI bao gồm một giá trị nhận dạng giao dịch riêng biệt (transactionId) để theo dõi các yêu cầu và tránh thực hiện giao dịch trùng lặp. DPA PHẢI phản hồi bằng một phản hồi thành công/thất bại.
Yêu cầu giao dịch
Sau khi nhận được yêu cầu từ một khách hàng, GTAF sẽ gửi một yêu cầu POST đến DPA. URL của yêu cầu là:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
trong đó userKey là CPID hoặc MSISDN. Nội dung yêu cầu là một phiên bản của TransactionRequest, bao gồm các trường sau:
{
"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.
}
Phản hồi giao dịch
DPA CHỈ ĐƯỢC tạo phản hồi 200-OK cho giao dịch được thực hiện thành công hoặc giao dịch được xếp hàng. Vui lòng xem Error Cases (Các trường hợp lỗi) để biết phản hồi dự kiến trong trường hợp xảy ra lỗi. Trong trường hợp giao dịch được xếp hàng, DPA chỉ điền trạng thái giao dịch và để trống các trường khác trong phản hồi. DPA PHẢI gọi lại GTAF bằng một phản hồi sau khi giao dịch trong hàng đợi được xử lý. Nội dung phản hồi là một phiên bản của TransactionResponse, bao gồm những thông tin chi tiết sau:
{
"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.
}
}
Nếu thiếu planActivationTime, GTAF PHẢI giả định rằng gói đã được kích hoạt.
Đăng ký CPID
Khi một ứng dụng hỗ trợ thông báo nhận được CPID mới từ điểm cuối CPID, ứng dụng đó sẽ đăng ký CPID với GTAF nếu các điều khoản của ứng dụng cho phép GTAF làm như vậy. Nếu ứng dụng đăng ký CPID thành công với GTAF, thì GTAF sẽ đăng ký CPID với DPA bằng lệnh gọi API sau:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
trong đó userKey là CPID và CLIENT_ID duy nhất được hỗ trợ là mobiledataplan. Nội dung yêu cầu là một phiên bản của RegisterCpidRequest và chứa thời gian sau đó CPID không thể dùng để gửi thông báo và có dạng như sau:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
API này chỉ phù hợp với những nhà mạng muốn hỗ trợ mô-đun Gói dữ liệu di động trong Dịch vụ Google Play. Để gửi thông báo một cách đáng tin cậy cho người dùng, DPA CÓ THỂ lưu trữ CPID đã đăng ký mới nhất cho mỗi người dùng. Vui lòng xem bài viết Chọn CPID để biết hướng dẫn về cách sử dụng CPID đã đăng ký để gửi thông báo.
DPA sẽ tạo phản hồi 200-OK nếu DPA liên kết thành công CPID với người dùng và lưu trữ CPID một cách liên tục. Vui lòng xem Error Cases (Các trường hợp lỗi) để biết phản hồi dự kiến trong trường hợp xảy ra lỗi.
Sự đồng ý
GTAF CÓ THỂ đưa ra yêu cầu sau để chuyển lựa chọn ưu tiên về sự đồng ý của người dùng cho hãng vận chuyển.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
trong đó userKey là CPID hoặc MSISDN. Nội dung yêu cầu là một phiên bản của SetConsentStatusRequest. Nếu thành công, nội dung phản hồi sẽ trống.
Mọi lệnh gọi từ GTAF đến DPA đều tuân theo điều khoản dịch vụ của ứng dụng Google thực hiện lệnh gọi. Tuỳ thuộc vào các ứng dụng mà DPA muốn hỗ trợ, nhà khai thác sẽ quyết định xem DPA có triển khai API này hay không. Nếu chọn triển khai Consent API, thì DPA PHẢI lưu trữ trạng thái đồng ý mới nhất cho từng người dùng. Vui lòng xem phần Chọn CPID để biết hướng dẫn về cách sử dụng thông tin trạng thái đồng ý.
Trong trường hợp thành công, DPA PHẢI trả về HTTP 200 OK với phần nội dung phản hồi trống. Vui lòng xem Các trường hợp lỗi để biết phản hồi dự kiến trong trường hợp xảy ra lỗi.