Động lực
Như đã đề cập trong phần tổng quan, tuỳ thuộc vào trường hợp sử dụng mà toán tử muốn hỗ trợ, DPA phải triển khai kết hợp API Chia sẻ gói dữ liệu di động của Google và API Tác nhân gói dữ liệu. Tài liệu này mô tả API Tác nhân gói dữ liệu mà Google sẽ 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à gói dữ liệu mua.
Xác thực
Trước khi GTAF có thể gọi, DPA phải xác thực GTAF. Trong quá trình giới thiệu nhà cung cấp dịch vụ, 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 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 chi tiết về cách GTAF xác thực chính nó với DPA.
Quốc tế hóa
Các yêu cầu GTAF gửi tới DPA bao gồm tiêu đề Chấp nhận ngôn ngữ cho biết ngôn ngữ mà các chuỗi con người có thể đọc được (ví dụ: nội dung mô tả kế hoạch) phải thuộc ngôn ngữ đó. Ngoài ra, 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ụ: "vi-VN") 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 đó.
Nội dung mô tả về API
GTAF sử dụng khoá người dùng để xác định thuê bao của toán tử khi truy vấn DPA của toán tử đó. Khi GTAF đang truy vấn DPA thay mặt 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, API Tác nhân gói dữ liệu đượ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 người dùng.
- Cơ chế truy vấn DPA cho các ưu đãi gói dữ liệu cho người dùng.
- Cơ chế thực hiện thay đổi đối với gói dữ liệu của người dùng (ví dụ: mua một gói mới).
- Cơ chế chia sẻ các CPID có thể dùng để gửi thông báo cho người dùng.
- Cơ chế chia sẻ các lựa chọn của người dùng về việc có nên đă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 giải thích chi tiết về từng thành phần API này. Trừ phi có lưu ý rõ ràng, tất cả thông tin liên lạc PHẢI diễn ra qua HTTPS (có chứng chỉ DPA SSL hợp lệ). Tuỳ thuộc vào các tính năng thực tế được hỗ trợ, toán tử MAY sẽ chọn triển khai tất cả hoặc một nhóm nhỏ các 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 về gói dữ liệu người dùng.
Hình 4 minh hoạ quy trình gọi được liên kết với một ứng dụng truy vấn trạng thái gói dữ liệu của người dùng và các thông tin khác về gói dữ liệu. Quy trình 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.
- Máy khách yêu cầu 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 tới AFAF.
- GTAF sử dụng khoá người dùng và mã nhận dạng ứng dụng để truy vấn toán tử DPA của toán tử. Các giá trị nhận dạng khách hàng được hỗ trợ là mobiledataplan và youtube. Khi DPA nhận được cuộc gọi có một trong các giá trị nhận dạng ứng dụng này, bạn phải phản hồi bằng thông tin gói mà ứng dụng có thể sử dụng.
- GTAF trả về thông tin yêu cầu cho ứng dụng khách và thông tin gói được GTAF lưu vào bộ nhớ đệm cho đến thời điểm DPA chỉ định hết hạn.
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 để nhận trạng thái gói:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Ứng dụng mà GTAF đang liên hệ với DPA sẽ xác định bằng cách sử dụng CLIENT_ID. Tuỳ thuộc vào thoả thuận giữa ứng dụng và nhà cung cấp dịch vụ Google, DPA có thể tuỳ chỉnh phản hồi cho GTAF. Trong trường hợp thành công, DPA PHẢI PHẢI trả về HTTP 200 OK với phần nội dung phản hồi đại diện cho một PlanStatus. Vui lòng xem phần Trường hợp lỗi để biết phản hồi dự kiến trong trường hợp có 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 các gói trả sau, expirationTime PHẢI là ngày lặp lại của gói (tức là khi dữ liệu được làm mới/tải lại).
Mỗi mô-đun gói có thể chứa nhiều Danh mục lưu lượng truy cập mô-đun kế hoạch (PMTCs)để lập mô hình 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
cho trò chơi và âm nhạc. Các PMTC sau đây được xác định trước: GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Theo dự kiến, các nhà vận hành sẽ liên hệ với từng nhóm Google để thống nhất về nhóm danh mục lưu lượng truy cập và ngữ nghĩa của các danh mục đó phù hợp với nhiều ứng dụng của Google.
Truy vấn các ưu đãi gói
GTAF đưa ra yêu cầu HTTP sau đây để nhận ưu đãi của gói từ nhà cung cấp dịch vụ:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
Ứng dụng mà GTAF đang liên hệ với DPA sẽ xác định bằng cách sử dụng CLIENT_ID. Tuỳ thuộc vào thoả thuận giữa ứng dụng và nhà cung cấp dịch vụ Google, DPA có thể tuỳ chỉnh phản hồi cho GTAF. Thông số ngữ cảnh không bắt buộc cung cấp ngữ cảnh của ứng dụng khi yêu cầu được thực hiện. Thông thường, đây là một chuỗi mà ứng dụng chuyển đến toán tử thông qua GTAF.
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 đại diện cho một PlanOffer. Vui lòng xem phần 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ự trình bày các gói dữ liệu cho người dùng. Ngoài ra, nếu ứng dụng chỉ có thể
hiển thị các kế hoạch x do giao diện người dùng hoặc các giới hạn khác và phản hồi chứa
y > x chỉ lập kế hoạch các kế hoạch x đầu tiên SHALL. GTAF chỉ chia sẻ tối đa 50 gói nếu ứng dụng truy vấn ưu đãi là mô-đun Gói dữ liệu di động thuộc Dịch vụ Google Play. Điều này giúp đảm bảo trải nghiệm người dùng tốt cho người dùng Dịch vụ Google Play.
Những sản phẩm bán thêm có filterTag dưới dạng một thông số tùy chọn, là một loạt các thẻ được đính kèm vào mỗi gói. Tất cả các bộ lọc 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
tuple<tag, displaytext/><quot;">. Filter là danh sách tổng hợp các bộ lọc sẽ được
hiển thị 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 sử dụng để lọc các ưu đãi.</tag,>
Xin lưu ý rằng toán tử PHẢI có một cơ chế để thực hiện yêu cầu mua hàng đối với bất kỳ ưu đãi nào mở rộng cho người dùng. Cơ chế mà qua đó người dùng sẽ bị tính phí cho giao dịch mua bất kỳ có thể được thông báo bằng GTAF bằng cách sử dụng tuỳ 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 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 SHALL bao gồm một mã nhận dạng giao dịch duy nhất (transactionId) để theo dõi các yêu cầu và tránh thực thi 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/không thành công.
Yêu cầu giao dịch
Sau khi nhận được yêu cầu từ khách hàng, GTAF sẽ gửi yêu cầu POST tới 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. Phần nội dung của 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 về giao dịch
DPA SHALL chỉ tạo phản hồi 200 OK cho một giao dịch được thực thi thành công hoặc một giao dịch đã xếp hàng đợi. Vui lòng xem phần Các trường hợp lỗi để biết thông tin phản hồi dự kiến cho trường hợp xảy ra lỗi. Trong trường hợp giao dịch đã đưa vào hàng đợi, DPA sẽ chỉ điền trạng thái giao dịch và để trống các trường khác trong nội dung phản hồi. DPA PHẢI gọi lại GTAF bằng một phản hồi sau khi hệ thống đã xử lý xong một giao dịch đã xếp hàng. Phần nội dung của phản hồi là một thực thể của transactionResponse bao gồm các 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 SHALL giả định rằng gói này đã được kích hoạt.
Đăng ký CPID
Khi một khách hàng hỗ trợ thông báo nhận được chỉ số CPI mới từ điểm cuối CPID, thì nó 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 khách hà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. Phần nội dung của yêu cầu là một thực thể của registerCpidRequest và chứa thời gian mà sau đó không thể dùng CPID để gửi thông báo và có dạng như sau:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
API này chỉ liên quan đến các nhà cung cấp dịch vụ 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 MAY lưu trữ chỉ số 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 ra phản hồi 200 OK nếu DPA liên kết thành công CPU với người dùng và liên tục lưu trữ DPA đó. Vui lòng xem phần 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 đây để chuyển tùy chọn đồng ý của người dùng đến nhà mạng.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
trong đó userKey là CPID hoặc MSISDN. Phần nội dung của yêu cầu là một bản sao của SetConsentStatusRequest. Nếu thành công, nội dung phản hồi sẽ trống.
Mọi cuộc gọi từ GTAF đến DPA đều tuân theo các điều khoản dịch vụ của ứng dụng Google thực hiện cuộc gọi. Tuỳ thuộc vào các ứng dụng mà DPA đang tìm cách hỗ trợ, nhà vận hành sẽ quyết định việc DPA có triển khai API này hay không. Nếu DPA chọn triển khai API lấy sự đồng ý, 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 bài viết Chọn CPID để biết hướng dẫn 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 phần Các trường hợp lỗi để biết thông tin phản hồi dự kiến cho trường hợp xảy ra lỗi.