Changelog
Stay organized with collections
Save and categorize content based on your preferences.
Data Plan Agent API
December 2019
- Introduced register CPID
API
definition for the DPA to implement.
- Added suggestions for how to generate the CPID and store it when the client
requests a new CPID.
- Added documentation for how to choose the CPID to be used for sending
notifications.
- Clarified how to determine user language preferences when GTAF calls the DPA
and when DPA calls GTAF.
October 2019
- Require a new CPID every time we contact the CPID endpoint. This can be
accomplished by adding a timestamp to the CPID generation algorithm.
- Remove planLanguage
from Offer
which until now
was marked as a required field.
September 2019
- Added support for data expiration notifications, distinguished from data
expiration warning notifications.
July 2019
- Clarified the possible client identifier values.
- Added support for account top up notifications.
- Relaxed CPID generation requirements from requiring a new CPID every time the
CPID endpoint is called.
- Add documentation
for different error
responses from GTAF when calling Mobile Data Plan Sharing API.
June 2019
- Updated DPA API specification requiring carriers to accept a _client id
as a
query parameter.
- Updated Mobile Data Plan Sharing API allowing carriers to share plan
information of a user for a particular client with Google.
- The order in which offers are shown to the user may not be the same as the
order in which offers are given to GTAF.
- GTAF may share more than 10 plans with Mobile Data Plan UI.
May 2019
- ExpirationTime is required unless the plan does not expire.
- Per RFC 6749, mark token_type as required in OAuth server response.
- Return the type of notifications that have been sent to the user when the
carrier pushes a plan status to GTAF.
April 2019
- AccountInfo is required for prepaid subscribers.
- Update recommended CPID generation method to include language in the plain
text when generating CPID.
- Removed support for moreInfoUrl, operatorLogoUrl, purchaseUrl from offers.
These fields were not supported by the mobile data plan UI. The change is
backwards compatible.
- Added support for sending notifications when a user is spending account
balance using data in a pay as you go state.
- Removed support for flex time windows from plan modules. The change is
backwards compatible. So, if an operator is sending us flex time windows, the
response will be accepted.
March 2019
- Remove offerInfo.promoMessage from the set of required fields. MDP does not
use this field when showing offers to the users.
- Fix documentation bug saying that the CPID must be URL encoded. Instead, GTAF
encodes the CPID per RFC2396
.
- Added requirements for push notifications.
February 2019
- Removed support for sharing PlanOffer with Google using data plan sharing
API.
January 2019
- Added guide for updating carrier configuration using the ISP portal.
- Added guide for OAuth implementation for the Data Plan Agent API.
- Renamed and reorganized the Mobile Data Plan Sharing API integration guide.
November 2018
- Added support for plan activation notifications.
- Added support for an APP_STORE plan module traffic category.
September 2018
- Added API to report user consent
to
operators.
- Added support for plans that periodically refresh their quota to PlanModule
and Offer
.
- Added support for expiry notifications.
- Renamed PlanModuleState to PlanState
.
This is a documentation change that should not affect operators.
August 2018
- Added the ability for carriers to specify account balance as part of a PlanStatus
.
June 2018
- Removed update, get methods for plan status and plan offers.
- Allowed coarse balance level to be populated at the same time when byte
balance or time balance are populated.
- Added connection type
to an Offer
.
- Added plan module state
field to PlanModule
to allow an operator to
indicate plans which the user has bought but have not been activated yet.
This is not a required field.
- DataPlan renamed to Plan
. This is a documentation
change that should not affect operators.
- Added formOfPayment
field to PlanOffer
allowing an operator to specify how the user will be charged for the
purchase. This defaults to deducted from plan balance.
May 2018
- Updated CPID response
to keep the
response backwards compatible.
- Added title for a PlanStatus
. The
title will be used to populate the header in the settings UI.
- Added module name and used bytes for a PlanModule
.
- Added a purchase response call back to GTAF.
March 2018
This update includes the following changes to the Data Plan Agent API. These
changes are relative to Data Plan API v4.2 hosted here
.
- Deprecates the following API calls:
- Querying user account (DPA_URL/{data_plan_key_string}/account).
- Querying purchased plans
(DPA_URL/{data_plan_key_string}/purchasedPlans).
- Changes the URL we call for data plan status. The new URL is described here
. The DPA is expected to return
an instance of PlanStatus
.
- Changes the URL we call for plan offers. The new URL is described here
. The DPA is expected to
return an instance of PlanOffer
.
- Changes the body of the request sent to DPA when purchasing a plan. Note
that API call
is the same. The
body of the request now contains an instance of TransactionRequest
. Note the
removal of a level of nesting compared to the previous version of the API.
- Response to a purchase request has changed. We take advantage of currency
type defined by Google protobuf. In response to a successful purchase, we
expect the response body to contain an instance of TransactionResponse
.
- If a
plan_id
is not specified, then the eligibility API MUST return all
the data plans that the user is eligible for. Previously this was optional.
- Adds an MSISDN registration endpoint for GTAF to register MSISDNs for
notifications with the DPA.
Google Mobile Data Plan Sharing API
March 2018
This update includes the following changes to the Google Mobile Data Plan
Sharing API:
- Introduces new API calls allowing an operator to push upsell offer
information to GTAF to be pushed further down to user devices. These new
calls allow an operator to push offers to Google.
- Introduces a last updated time field in a PlanGroup.
- Removes data credit percentage field from flex time window.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License
, and code samples are licensed under the Apache 2.0 License
. For details, see the Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2023-10-03 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2023-10-03 UTC."],[[["\u003cp\u003eThe Data Plan Agent API enables carriers to share user plan information and offers with Google, supporting functionalities like data plan sharing and notifications.\u003c/p\u003e\n"],["\u003cp\u003eUpdates to the API have focused on enhancing data plan representation, improving notification capabilities, refining the offer process, and introducing a CPID for client identification.\u003c/p\u003e\n"],["\u003cp\u003eKey changes include introducing a new CPID system, supporting various notification types (expiration, top-up, etc.), and standardizing data formats for plan information and offers.\u003c/p\u003e\n"],["\u003cp\u003eGoogle's Mobile Data Plan Sharing API enables carriers to proactively push offers and updates to GTAF, improving user experience with real-time information.\u003c/p\u003e\n"],["\u003cp\u003eThe API has evolved over time to improve data accuracy, security, and overall functionality for both carriers and end-users.\u003c/p\u003e\n"]]],["The Data Plan Agent API updates include defining the CPID registration, generation, and usage for notifications. Language preference handling was clarified for GTAF/DPA interactions. Support was added for various notifications, including data expiration, account top-up, plan activation, and pay-as-you-go spending. API modifications were made for sharing plan information with Google, including offer updates and plan status changes. Changes also removed and deprecated specific API calls. Additional changes provided enhancements for error handling and client identifier requirements.\n"],null,["# Changelog\n\nData Plan Agent API\n-------------------\n\nDecember 2019\n-------------\n\n1. Introduced [register CPID](./agent_api_specification#register-cpid) API definition for the DPA to implement.\n2. Added suggestions for how to generate the CPID and store it when the client requests a new CPID.\n3. Added documentation for how to choose the CPID to be used for sending notifications.\n4. Clarified how to determine user language preferences when GTAF calls the DPA and when DPA calls GTAF.\n\nOctober 2019\n------------\n\n1. Require a new CPID every time we contact the CPID endpoint. This can be accomplished by adding a timestamp to the CPID generation algorithm.\n2. Remove *planLanguage* from [Offer](./reference/rest/v1/Offer) which until now was marked as a required field.\n\nSeptember 2019\n--------------\n\n1. Added support for data expiration notifications, distinguished from data expiration warning notifications.\n\nJuly 2019\n---------\n\n1. Clarified the possible client identifier values.\n2. Added support for account top up notifications.\n3. Relaxed CPID generation requirements from requiring a new CPID every time the CPID endpoint is called.\n4. Add [documentation](/mobile-data-plan/dataplansharing_error_cases) for different error responses from GTAF when calling Mobile Data Plan Sharing API.\n\nJune 2019\n---------\n\n1. Updated DPA API specification requiring carriers to accept a _client*id* as a query parameter.\n2. Updated Mobile Data Plan Sharing API allowing carriers to share plan information of a user for a particular client with Google.\n3. The order in which offers are shown to the user may not be the same as the order in which offers are given to GTAF.\n4. GTAF may share more than 10 plans with Mobile Data Plan UI.\n\n### May 2019\n\n1. ExpirationTime is required unless the plan does not expire.\n2. Per RFC 6749, mark token_type as required in OAuth server response.\n3. Return the type of notifications that have been sent to the user when the carrier pushes a plan status to GTAF.\n\n### April 2019\n\n1. AccountInfo is required for prepaid subscribers.\n2. Update recommended CPID generation method to include language in the plain text when generating CPID.\n3. Removed support for moreInfoUrl, operatorLogoUrl, purchaseUrl from offers. These fields were not supported by the mobile data plan UI. The change is backwards compatible.\n4. Added support for sending notifications when a user is spending account balance using data in a pay as you go state.\n5. Removed support for flex time windows from plan modules. The change is backwards compatible. So, if an operator is sending us flex time windows, the response will be accepted.\n\n### March 2019\n\n1. Remove offerInfo.promoMessage from the set of required fields. MDP does not use this field when showing offers to the users.\n2. Fix documentation bug saying that the CPID must be URL encoded. Instead, GTAF encodes the CPID per [RFC2396](https://www.ietf.org/rfc/rfc2396.txt).\n3. Added requirements for push notifications.\n\n### February 2019\n\n1. Removed support for sharing PlanOffer with Google using data plan sharing API.\n\n### January 2019\n\n1. Added guide for updating carrier configuration using the ISP portal.\n2. Added guide for OAuth implementation for the Data Plan Agent API.\n3. Renamed and reorganized the Mobile Data Plan Sharing API integration guide.\n\n### November 2018\n\n1. Added support for plan activation notifications.\n2. Added support for an APP_STORE plan module traffic category.\n\n### September 2018\n\n1. Added API to report [user consent](./agent_api_specification#consent) to operators.\n2. Added support for plans that periodically refresh their quota to [PlanModule](./reference/rest/v1/Plan#PlanModule) and [Offer](./reference/rest/v1/Offer).\n3. Added support for expiry notifications.\n4. Renamed PlanModuleState to [PlanState](./reference/rest/v1/Plan#PlanState). This is a documentation change that should not affect operators.\n\n### August 2018\n\n1. Added the ability for carriers to specify account balance as part of a [PlanStatus](./reference/rest/v1/operators.planStatuses#PlanStatus).\n\n### June 2018\n\n1. Removed update, get methods for plan status and plan offers.\n2. Allowed coarse balance level to be populated at the same time when byte balance or time balance are populated.\n3. Added *connection type* to an [Offer](./reference/rest/v1/Offer).\n4. Added *plan module state* field to [PlanModule](./reference/rest/v1/Plan#PlanModule) to allow an operator to indicate plans which the user has bought but have not been activated yet. This is not a required field.\n5. DataPlan renamed to [Plan](./reference/rest/v1/Plan). This is a documentation change that should not affect operators.\n6. Added *formOfPayment* field to [PlanOffer](./reference/rest/v1/PlanOffer) allowing an operator to specify how the user will be charged for the purchase. This defaults to deducted from plan balance.\n\n### May 2018\n\n1. Updated [CPID response](./reference/rest/v1/CPIDResponse) to keep the response backwards compatible.\n2. Added title for a [PlanStatus](./reference/rest/v1/operators.planStatuses#PlanStatus). The title will be used to populate the header in the settings UI.\n3. Added module name and used bytes for a [PlanModule](./reference/rest/v1/Plan#planmodule).\n4. Added a purchase response call back to GTAF.\n\n### March 2018\n\nThis update includes the following changes to the Data Plan Agent API. These\nchanges are relative to Data Plan API v4.2 hosted\n[here](https://github.com/aterzis-google/data-plan-api/blob/master/mobile_data_plan_api_v4_2.md).\n\n1. Deprecates the following API calls:\n 1. Querying user account (DPA_URL/{data_plan_key_string}/account).\n 2. Querying purchased plans (DPA_URL/{data_plan_key_string}/purchasedPlans).\n2. Changes the URL we call for data plan status. The new URL is described [here](./agent_api_specification#plan-status). The DPA is expected to return an instance of [PlanStatus](./reference/rest/v1/operators.planStatuses#PlanStatus).\n3. Changes the URL we call for plan offers. The new URL is described [here](./agent_api_specification#upsell-offers). The DPA is expected to return an instance of [*PlanOffer*](./reference/rest/v1/PlanOffer).\n4. Changes the body of the request sent to DPA when purchasing a plan. Note that [API call](./agent_api_specification#data-purchase) is the same. The body of the request now contains an instance of [TransactionRequest](./reference/rest/v1/TransactionRequest). Note the removal of a level of nesting compared to the previous version of the API.\n5. Response to a purchase request has changed. We take advantage of currency type defined by Google protobuf. In response to a successful purchase, we expect the response body to contain an instance of [TransactionResponse](./reference/rest/v1/TransactionResponse).\n6. If a `plan_id` is not specified, then the eligibility API MUST return all the data plans that the user is eligible for. Previously this was optional.\n7. Adds an MSISDN registration endpoint for GTAF to register MSISDNs for notifications with the DPA.\n\nGoogle Mobile Data Plan Sharing API\n-----------------------------------\n\n### March 2018\n\nThis update includes the following changes to the Google Mobile Data Plan\nSharing API:\n\n1. Introduces new API calls allowing an operator to push upsell offer information to GTAF to be pushed further down to user devices. These new calls allow an operator to push offers to Google.\n2. Introduces a last updated time field in a PlanGroup.\n3. Removes data credit percentage field from flex time window."]]
