Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
In this document you will learn how to consume the MG2 Newsletter Widget API.
MG2 Newsletter Widget API is a Javascript library which allows you to consume, easily and quickly, every feature in the MG2 Newsletter Widget.
In order to consume the API, the page needs to include a reference to MG2Widget newsletterwidget.min.jsand a container element as the following example shows:
Parameter
Description
email
Subscriber’s email. If this param is not specified, it will be looked for in the cookie. If it doesn’t exist, it will be asked to user.
categoryIdsList
List of Category IDs. It needs to be specified as an array list. If this param is not specified, widget will show all the categories. (Omitted in unsubscribe flow)
newsletterIdsList
List of Newsletter IDs. It needs to be specified as an array list.
Open widget flow: If this param is not specified, widget will show all the newsletters.
Unsubscribe newsletters flow: If this param is not specified, widget will unsubscribe from all the newsletters.
viewMode
This param specifies the view mode in which newsletters are shown. There are two options: Tabs mode (1) or List mode (2). Default mode is Tabs. (Omitted in unsubscribe flow)
defaultCategoryId
This param specifies the category that will be opened by default.
siteCode
If this param is specified, only preferences for that NewspaperId will be displayed.
isModal
If this param is specified and has value 'true' then widget will be displayed in Modal mode
subscriberOnly
If this param is specified and has value 'true' then widget will display only Subscriber available newsletters. Otherwise only non-subscriber newsletters will be displayed.
showAll
If this param is specified and has value 'true' and 'subscriberOnly' has value 'true' then widget will display all newsletters. Otherwise result depends on 'subscriberOnly' flag.
Open default category.
Force a View Mode for Preferences.
Display widget as modal.
Displays newsletters filtered by SubscriberOnly criteria.
Displays all newsletters.
LINKS: Please apply URLEncode to each QueryString parameter.
Change Preferences: http://{YOUR_WIDGET_DOMAIN}/updatepreference?email=subscriber%40email.com
DISCLAIMER
Product Information contained within this document, including technical information and functional specifications, is subject to change without notice. Naviga reserves the right to make any changes to the information in this document at any time without notice. Naviga makes no warranty, representation, or guarantee regarding the suitability of its products and services for any particular purpose.
New subscriptions that have been created through InApp marketplaces rather than through the Naviga Subscribe platform are referred to as "Newstart InApp" subscriptions. This page provides an overview of the steps that must be followed in order to successfully migrate a client from the previous External Payments system to the new Webhooks system.
This will allow the client to begin processing the new InApp Newstart that will be created from an external app using PurchaseAPI, as well as the Webhooks notification that will be created from the external markets using Webhooks API.
A minimum Subscribe version of 3.16.3.6 and above is required to use the new InApp endpoints.
In order to make sure that the notifications have been correctly received, it will be necessary to set up the authentication credentials, such as API keys, access tokens, etc., that have been associated with the in-app market.
Credentials should be in JavaScript Object Notation (JSON) format.
Apple V1
Credentials should be in String format of 32 characters.
Apple V2
Credentials should be in JSON Web Token (JWT) format.
The URL of the Webhook has to be updated in the specific marketplace console (Google, Apple V1, Apple V2) in order to receive the notification status information in the new Webhooks flow.
POST “Webhooks/Google/{MediaGroup}/{ClientCode}/{PaperCode}”
Apple V1
POST “Webhooks/Apple/V1/{MediaGroup}/{ClientCode}/{PaperCode}”
Apple V2
POST “Webhooks/Apple/V2/{MediaGroup}/{ClientCode}/{PaperCode}”
For Newstarts InApp subscriptions, the new URL endpoints must be used along with the new bearer authentication.
POST {SubscribeApiUrl}/Purchases/InApp
This endpoint is used to create a Newstart InApp subscription.
Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.
Authorization*
String
JSON Web Token used for security purposes
X-SourceSystem*
String
To identify the consumer or the Source System
X-ClientCode*
String
Client Code of the Tenant
X-PaperCode*
String
Paper Code of the Tenant
X-MediaGroupCode*
String
Media Group Code of the Tenant
CustomerRegistrationId*
String
Unique identifier of a customer in Naviga System
OfferId*
Integer
Unique identifier of the offer in Naviga System
OfferGroupId*
Integer
Unique identifier of the offer group in Naviga System
OfferCode
String
Unique code of the offer in Naviga System
AppleInfo.Receipt*
String
Receipt information for the Apple InApp market.
It is required only if it is an Apple InApp Newstart.
GoogleInfo.Receipt*
String
Receipt information for the Google InApp market.
It is required only if it is an Google InApp Newstart.
Subscriber.Email
String
Email of the subscriber
Subscriber.Country
String
Country of the subscriber
Subscriber.CompanyType
String
Company type of the subscriber
Subscriber.CompanyName
String
Company name of the subscriber
Subscriber.Title
String
Title of the subscriber
Subscriber.LastName
String
Last name of the subscriber
Subscriber.FirstName
String
First name of the subscriber
PaymentTypeId*
Integer
Unique identifier of the payment type in Naviga System
StartDate*
dateTime
Start date of the subscription
EmailAddress*
String
Email address of the subscriber
Subscriber.Phone
String
Phone of the subscriber
Product.MerchantProductId
String
Unique identifier of the merchant product
Product.ProductQuantity
Integer
Quantity of the product required
Product.ExternalProductId
String
Unique identifier of the external product
Products
Array
RegistrationId
Integer
Unique identifier of a registration in Naviga System
Product.ProductId
Integer
Unique identifier of the product
For detailed implementation steps of the Newstart InApp migration from the old ExternalPayments system to the new Webhooks system, please refer to the internal Confluence documentation.
Naviga Implementation team should migrate the data for existing InApp subscriptions from the old External Payments database to the new tables in the Subsvc database.
Google.VerifyReceiptCredential
The client provides the credentials in JSON format. The value differs depending on the newspaper client.
Apple V1
Apple.VerifyUrl
The universal URL endpoint for verification of receipts. The value remains the same for all clients.
Apple V1
Apple.VerifySecret
The client provides the credentials in String format of 32 characters. The value differs depending on the newspaper client.
Apple V2
Apple.AppleTokenSecretWebhooksApi
The client provides the credentials in JWT format. The value differs depending on the newspaper client.
Flow.Purchase.InApp.Redirect
The value should be set for a specific client. The default value has been set to 1 (true).
If the value has been set to 0 (false), the Purchase API will process the Newstart subscription.
If the value has been set to 1 (true), the request will be redirected to the Subscriptions API to process the Newstart subscription.
InAppNotification.NotificationRetryLimitWebhooksApi
Whenever the system finds that the processed status of an InApp notification does not indicate "OK," it will attempt to process the notification again.
This setting determines the maximum number of times that the notification can be reprocessed.
Set the following information in the [EventTypes] and [NewspaperEventProcessorAssignments] tables based on the specific market to be configured:
Set the configuration for the event type, GOOGLEVERIFYRECEIPT (1195), to have active = 1 (true) and triggers_post = 1 (true).
It should also be associated with NewspaperEventProcessorAssignments, with the 'EventProcessorId' value set to 41 (Google).
Set the configuration for the event type, APPLEVERIFYRECEIPT (1194), to have active = 1 (true) and triggers_post = 1 (true).
It should also be associated with NewspaperEventProcessorAssignments, with the 'EventProcessorId' value set to 43 (Apple).
A new bearer authentication should be generated for the client. The bearer token should have PurchaseAPI resource added with the 'write' access.
Hangfire is integrated into the OnPremise API, which manages background jobs and scheduled tasks.
The below-listed MG2 Control API settings should be in place.
OnPremiseStorageConnectionString
This setting is used to define the "DB Connection string" in order to designate a specific database as a repository for managing queue(s). Example value: Data Source=IP;Initial Catalog=MG2_Control;User Id=xxxxx;Password=xxxxx;
SubConConnectionString
This is a global setting that specifies the connection string for connecting to the Subsvc DB. Example value:
Data Source=IP;Initial Catalog=subsvc_SomeClient_test;Persist Security Info=True;User ID=xxxxx;pwd=xxxxx;
MG2API
This setting is used as the base URL for calling the Subscribe APIs. Example value: http://aws-test.subscriberconcierge.com/
Before configuring Hangfire, the following stored procedures must exist:
dbo.OnPremise_InAppRetryNotification_GetData
dbo.OnPremise_StopExternalSubscriptions_GetData
Hangfire will generate a task cycle that will run every time as specified in the input model's instructions.
POST: https://aws-test.subscriberconcierge.com/Notifications/InApp/Retry/Configure
Sample Input Model:
The task will retry failed market notifications by calling the Webhooks API Retry endpoint (POST: https://aws-test.subscriberconcierge.com/Notifications/{id}/Retry) with the same request Headers used in the request.
Hangfire will generate a task cycle that will run every time as specified in the input model's instructions.
POST: https://aws-test.subscriberconcierge.com/Notifications/InApp/Retry/Configure
Sample Input Model:
This task searches the Subscribe database for external subscriptions with an active status (L) and a stop date prior to the current date (< today). It then calls the SubscriptionsAPI endpoint (POST: https://aws-test.subscriberconcierge.com/ExternalSubscription/{0}/Stop) with the same request Headers used in the request to stop each external subscription.
External markets such as GooglePlay or Apple may notify of an expiry date in the future; in this case, wait for this Hangfire task to be processed, which will stop the subscription at the appropriate time.
To remove a Notification or External Subscription task that has been created, call the Webhooks API endpoint mentioned below.
DELETE: https://aws-test.subscriberconcierge.com/Notifications/InApp/Retry/Remove/{taskKey}
Sample Input Model:
Hangfire is an open-source framework that helps to create and process background jobs, and the Hangfire server operates within the OnPremise API because this is an ASP.NET Framework web site hosted on IIS.
The Hangfire server is subject to the same events as a website (such as Application_Start, Application_End, etc.), causing it to simply shut down if the website becomes inactive.
For OnPremise API website configuration, please refer to the Confluence documentation.
Firefly is the system of record for Entitlement recognition. Each time a Registration links a Subscription on Naviga side, a license needs to be created in Firefly.
Method
URL
POST
/users/entitle/DTIC/
Parameter
Type
Description
Required?
Default
userGUID
GUID
Gannett User ID
Y
none
secret
string
Firefly external secret (currently)
Y
none
items/item/siteCode
string
Gannett Site Code, previously MarketID
Y
none
items/item/AccountNumber
string
AccountNumber
Y
none
items/item/ProductCode
string
Maps to Naviga paperCode field
Yes, in case multiple products sold in the market
none
items/item/serviceCodes
array
Array of the service codes as defined in Naviga
N
"digital"
SiteCode: MG2 Control Setting, formerly MarketID
ProductCode: our Paper Code, pulled from Newspapers table
ServiceCode:Service Code, pulled from Service_Types
For more information please see our internal documentation on Sharepoint: Document_1, Document_2
DISCLAIMER
Product Information contained within this document, including technical information and functional specifications, is subject to change without notice. Naviga reserves the right to make any changes to the information in this document at any time without notice. Naviga makes no warranty, representation, or guarantee regarding the suitability of its products and services for any particular purpose.
Entitlements are any type of content that a user might want to access, for example:
eEdition Access (code: eedition)
iPad App (code: ipad)
Benefits (code: benefits)
Rewards (code: rewards)
If you are using Naviga's mobile apps please find the info here on how to setup entitlement.
Access Levels illustrate a subscription position to a given Entitlement, for example:
Premium: You are entitled to access content.
Upgrade: You are not entitled to access content but you can upgrade your subscription to get access.
Purchase: You are not entitled to access content and you cannot upgrade your subscription. You need purchase a new one instead.
To determine access to a specific Entitlement, each Subscription is coded with a “Household Subscription Level”, which is a numeric value that it’s used to calculate its access level.
The Access page is a central place where the users can land from different web pages, so they can be redirected to different sites depending on their access level and the Entitlement they are trying to access to.
If the user is logged-in, an authorization process is carried out behind the scenes followed by a redirect.
In contrast, if the user is not logged-in, the Access page shows up for the user, exposing different actions the user can do, like starting a login process, a new subscription purchase, a new registration flow, an existing subscription activation, etc.
The Access page needs to receive two query string parameters to operate:
EntitlementCode: It’s the code that identifies the Entitlement.
SiteCode: It’s the code that identifies the publication the user is willing to access.
Each Entitlement might be linked to one or any many publications. Settings such as URLs, credentials, etc. are based on that combination.
In both scenarios, if the parameter is not provided, the Access page will use a default value which might cause undesired behaviors.
The possible values for each parameter will be provided in a separated client implementation document.
The Subscribe API is a centralized API used across every Naviga Client, not only for our applications but client’s applications. Among its functionalities, it exposes endpoints to handle Users and Entitlements.
The Subscribe API needs to receive five header parameters to operate:
X-MediaGroupCode, X-ClientCode, X-PaperCode: Three parameters used by the API to identify the tenant to use.
X-SourceSystem: The string used to identify who the consumer is.
Authorization: JSON web token used for security purposes.
X-CallerId: Customer Registration Id that belongs to the user that triggers the action - optional parameter
Every parameter listed above is a required field, except X-CallerId is optional.
Note: These parameter values will be provided in a separated client implementation document.
This is our recommended option if the Entitlement website/application wants to handle authentication (via the Authentication System) and authorization (via the Subscribe API) processes.
In this case, the user authentication ticket value and expiration will be managed on the Entitlement end.
Note: If Naviga is the Authentication System, the integration point is also the Subscribe API.
Use Case 1 (Non-Logged-In user wants to access content)
Pre-Conditions
The user is in a logged-out state in the Entitlement website/app.
The user has at least one subscription linked in Subscriber Concierge.
Flow
The User enters the Entitlement website/app.
The Entitlement website/app asks the user to login. Note: The login process might vary depending on the Authentication System that the client is integrated to.
The User enters their credentials and finish the login process. Note: Remember that if the Authentication System is Naviga, Subscribe API has the necessary endpoints to perform the Authentication.
The Entitlement website/app creates an authentication ticket on their end by using User ID.
The Entitlement website/app checks their access level through Subscribe API (Digital Access endpoint) with User ID and Code.
Subscribe API returns Access level (See section Access Levels in Defining some concepts). Also, if Access level = Premium, it creates an Access event.
The Entitlement website/app analyzes the response and, only if the access level is Premium, the Entitlement Content is displayed.
Use Case 2 (Logged-In user wants to access content)
Pre-Conditions
The user is in a logged-in state in the Entitlement website/app.
The user has at least one subscription linked in Subscriber Concierge.
Flow
The User enters the Entitlement website/app. Entitlement
The Entitlement website/app recognizes the user is already logged-in.
The Entitlement website/app checks their access level through Subscribe API (Digital Access endpoint) with User ID and Entitlement Code.
Subscribe API returns Access level (See section Access Levels in Defining some concepts). Also, if Access level = Premium, it creates an Access event.
The Entitlement website/app analyzes the response and, only if the access level is Premium, the Entitlement Content is displayed.
Use Case 3 (User wants to access web content from eNotify)
Pre-Conditions
The user has received an eNotify Email.
The user has at least one subscription linked in Subscriber Concierge.
Flow
The User their mailbox and reads eNotify email. Note: Naviga sends daily emails (eNotify) to subscribers to access their Entitlements.
eNotify email will contain a link to redirect the user to the Entitlement website. Note: In the case the Entitlement website allows it, eNotify could pass UserID and Entitlement Code via Querystring. E.g. https://[EDITIONLINK]/?EntitlementCode=[ABCDEF]&custregid=[XXXXXXXX]
The User clicks the eNotify link and gets redirected to the Entitlement website.
The Entitlement website recognizes the user by… A. QueryString parameters provided by Naviga: Go to step #5. B. Previously created authentication ticket: Go to step #5. Note: If the user cannot be authenticated, the website needs to ask the user to login.
The Entitlement website checks their access level through Subscribe API (Digital Access endpoint) with User ID and Entitlement Code.
Subscribe API returns Access level (See section Access Levels in Defining some concepts). Also, if Access level = Premium, it creates an Access event.
The Entitlement website/app analyzes the response and, only if the access level is Premium, the Entitlement Content is displayed.
For those scenarios where the Entitlement website/application cannot handle user management flows, you can rely on our Access page which is capable to authenticate and authorize users (the authentication ticket value and expiration will be managed between Naviga and the Authentication System).
After performing an authentication and authorization process successfully, the Access page returns a token that should be stored on the Entitlement end for future Access verification via the Subscribe API.
Use Case 1 (User enters wants to access content – NO token)
Pre-Conditions
The user has at least one subscription linked in Subscriber Concierge.
The user doesn’t have a token in the Entitlement website/app.
Flow
The User enters the Entitlement website/app.
The User gets redirected to the Access page because it doesn’t have any generated token previously. Note: Access page needs to receive the proper Entitlement Code via QueryString otherwise it would use a default one.
The Access page asks the user to log in. Note: If the user is already logged in, it goes to Step #5 directly.
The User enters their credentials and finish the login process.
The Access page checks their access level for the given Entitlement through Subscribe API (Digital Access endpoint) with User ID and Entitlement Code.
Subscribe API returns Access level (See section Access Levels in Defining some concepts) and token. Also, if Access level = Premium, it creates an Access event.
The Access page analyzes the response and, only if the access level is Premium, it redirects the user to Entitlement website, using the token as a QueryString parameter.
The Entitlement website stores the token for future verification and displays content to user.
Use Case 2 (User enters wants to access content – Valid token)
Pre-Conditions
The user has at least one subscription linked in Subscriber Concierge.
The user does have a valid token in the Entitlement website/app.
Flow
The User enters the Entitlement website/app.
The Entitlement site calls Subscribe API (DigitalAccess/token endpoint) sending the token.
Subscribe API indicates whether the user is authorized. If so, it also creates an Access event.
The Entitlement Site displays content to the user.
Use Case 3 (User enters wants to access content – Invalid/Expired token)
Pre-Conditions
The user has at least one subscription linked in Subscriber Concierge.
The user have an invalid/expired token in the Entitlement website/app.
Flow
The User enters the Entitlement website/app.
The Entitlement site calls Subscribe API (DigitalAccess/token endpoint) sending the token.
Subscribe API returns the user is not authorized.
The Entitlement site redirects the User to the Access page to generate a new token. (Use case 1, Step 2).
Use Case 4 (User wants to access web content from eNotify)
Pre-Conditions
The user has received an eNotify Email.
The user has at least one subscription linked in Subscriber Concierge.
Flow
The User their mailbox and reads eNotify email. Note: Naviga sends daily emails (eNotify) to subscribers to access their Entitlements.
eNotify email will contain a link to redirect the user to the Naviga Access Page.
The User clicks the eNotify link and gets redirected to the Naviga Access Page. (Use Case 1, Step 2)
The access page could receive multiple query string parameters.
Note: To avoid any kind of issues, please make sure you use URL Encode on every parameter.
EntitlementCode: The code that identifies the Entitlement. (See section “Defining some concepts” for more information). Alphanumeric.
SiteCode: The code that identifies the publication the user is willing to access. Alphanumeric.
URL example: https://myNavigaURL.com/Access?EntitlementCode=eEdition&SiteCode=NAV
FromURL: The URL the user should be redirected after the authorization process, instead of the URL provided by the Subscribe API.
Mode: The mode the Update Subscription page should load with if the user has Access Level = Upgrade. Possible values:
Add: The page will provide products to add to the subscription.
Up: The page will provide different offers to change the subscription.
PID: The promotion ID that will be sent as a part of the URL for Subscription Panel (Purchase flow)
ZipCode: The Zip Code that will be sent as a part of the URL for Subscription Panel (Purchase flow)
This is the most important endpoint for this integration. It evaluates whether a user has access to Entitlement content.
Method
URL
POST
/DigitalAccess
Type
Params
Values
Required?
HEAD
HEAD
HEAD
HEAD
HEAD
HEAD
BODY
BODY
BODY
X-MediaGroupCode
X-ClientCode
X-PaperCode
Authorization
X-SourceSystem
X-CallerId
CustomerRegistrationId
EntitlementCode
Device
string
string
string
string
string
string
string
string
string
yes
yes
yes
yes
yes
yes
yes
Yes
yes
CustomerRegistrationId: User ID returned by the Authentication System.
EntitlementCode: Code that identifies the entitlement.
Device: User Agent of the device the user is using to access content.
Status
Response
200
{
"Code": 0,
"Errors": [
{
"Message": "string",
"Code": "string",
"Type": {
"Id": 0,
"Code": "string"
},
"ErrorSource": "string"
}
],
"Result": {
"IsAuthorized": true,
"eEditionUrl": "string",
"AccessLevel": "string",
"Token": "string"
}
}
400
{"error":"Authorization is missing."}
400
{"error":"X-SourceSystem is missing."}
400
{"error":"request cannot be null."}
401
{"error":"Invalid X-AuthToken."}
401
{"error":"Invalid X-SourceSystem."}
500
{"error":"Something went wrong. Please try again later."}
Only used in Hybrid Approach. It verifies whether the token generated by Naviga Access page is still valid.
Method
URL
POST
/DigitalAccess/Token
Type
Params
Values
Required?
HEAD
HEAD
HEAD
HEAD
HEAD
HEAD
BODY
X-MediaGroupCode
X-ClientCode
X-PaperCode
Authorization
X-SourceSystem
X-CallerId
Token
string
string
string
string
string
string
string
yes
yes
yes
yes
yes
yes
yes
Token: Token created on an Entitlement Access authorization.
Status
Response
200
{
"Code": 0,
"Errors": [
{
"Code": "string",
"Message": "string"
}
],
"Result": {
"IsAuthorized": true
}
}
400
{"error":"Authorization is missing."}
400
{"error":"X-SourceSystem is missing."}
400
{"error":"request cannot be null."}
401
{"error":"Invalid X-AuthToken."}
401
{"error":"Invalid X-SourceSystem."}
500
{"error":"Something went wrong. Please try again later."}
Authenticates the user in the proper Authentication System and returns the data necessary to create the proper cookies.
Method
URL
POST
/Authenticate
Type
Params
Values
Required?
HEAD
HEAD
HEAD
HEAD
HEAD
HEAD
BODY
BODY
X-MediaGroupCode
X-ClientCode
X-PaperCode
Authorization
X-SourceSystem
X-CallerId
LoginName
Password
string
string
string
string
string
string
string
string
yes
yes
yes
yes
yes
yes
yes
yes
LoginName: Login name or email of the user.
Password: User’s password.
Status
Response
200
{
"Code": 0,
"Errors": [
{
"Message": "string",
"Code": "string",
"Type": {
"Id": 0,
"Code": "string"
},
"ErrorSource": "string"
}
],
"Result": {
"Authenticated": true,
"CookieContent": [
{
"Name": "string",
"Content": "string"
}
],
"CustomerRegistrationId": "string",
"EncryptedCustomerRegistrationId": "string"
}
}
400
{"error":"Authorization is missing."}
400
{"error":"X-SourceSystem is missing."}
400
{"error":"request cannot be null."}
401
{"error":"Invalid X-AuthToken."}
401
{"error":"Invalid X-SourceSystem."}
500
{"error":"Something went wrong. Please try again later."}
Sends an email to the user with a link to reset the password.
Method
URL
POST
/ForgotPassword
Type
Params
Values
Required?
HEAD
HEAD
HEAD
HEAD
HEAD
HEAD
BODY
BODY
X-MediaGroupCode
X-ClientCode
X-PaperCode
Authorization
X-SourceSystem
X-CallerId
LoginName
ReturnUrl
string
string
string
string
string
string
string
string
yes
yes
yes
yes
yes
yes
yes
yes
LoginName: Login name or email of the user.
ReturnURL: Where the user has to be redirected after the password is changed.
Status
Response
200
Response will be an object containing the list of users
{
"Code": 0,
"Errors": [
{
"Message": "string",
"Code": "string",
"Type": {
"Id": 0,
"Code": "string"
}
}
],
"Result": {
"PasswordResetLinkSent": true
}
}
400
{"error":"Authorization is missing."}
400
{"error":"X-SourceSystem is missing."}
400
{"error":"request cannot be null."}
401
{"error":"Invalid Authorization."}
401
{"error":"Invalid X-SourceSystem."}
500
{"error":"Something went wrong. Please try again later."}
This document is currently being revised
Subscription Panel application loads.
User clicks on either landing or the Subscription Panel calls GET/Offers. Sends offerGroupId and postal code to fetch details.
Subscription Panel then calls POST/subscriptionCost to fetch current taxes and cost.
Subscription Panel calls GET/user to check whether the user already exists. If the user does not already exist, it calls creates the user via POST/user.
User enters the address information. Then, Subscription Panel calls GET/address/standardization to standardize the current address.
Subscription Panel calls POST/Subscriptions/ActiveCheck to check whether this user already has an active subscription. If an active subscription exists, it returns an error.
Subscription Panel renders iframe with the edgil Javascript, which in turn calls:
POST/Billing/PaymentSession/StartPaymentSession - opens the iframe and generates a token
POST/Billing/PaymentSession/EndPaymentSession - saves credit card information and payment system
User clicks submit in Subscription Panel, and the Subscription Panel calls POST/Subscriptions to create the new subscription.
GET/Offers - this endpoint checks for the current offers.
Parameter Type
Parameter
Data Type
Required?
Description
Header
X-MediaGroupCode
string
Y
Code that designates the circulation system.
Header
X-ClientCode
string
Y
Code that designates the client.
Header
X-PaperCode
string
Y
Code that designates the newspaper.
Header
X-SourceSystem
string
Y
Code that designates the application.
Header
Authorization
string
Y
Authorization token.
Header
X-RequestId
integer
Y
Defines where to look for the user. 1 = User Provider; 2 = Naviga's database; 0 User provider and Naviga's database (recommended)
Query string
postalCode
integer
Y
Postal code
Query string
request.offerGroupId
integer
Y
Offer Group ID
The following is a cURL request example:
The following is a json example response from the /Offers endpoint.
POST/subscription/cost - the checks the current cost and tax for a particular offer
Parameter Type
Parameter
Data Type
Required?
Description
Header
X-MediaGroupCode
string
Y
Code that designates the circulation system.
Header
X-ClientCode
string
Y
Code that designates the client.
Header
X-PaperCode
string
Y
Code that designates the newspaper.
Header
X-SourceSystem
string
Y
Code that designates the application.
Header
Authorization
string
Y
Authorization token.
Header
X-RequestId
integer
Y
Defines where to look for the user. 1 = User Provider; 2 = Naviga's database; 0 User provider and Naviga's database (recommended)
Request body
integer
Y
JSON object (see request example below).
The following is a cURL request example:
The following is a json example response from the Subscriptions/Cost endpoint:
GET /User - the endpoint checks whether the user's email already exists
Parameter Type
Parameter
Data Type
Required?
Description
Header
X-MediaGroupCode
string
Y
Code that designates the circulation system.
Header
X-ClientCode
string
Y
Code that designates the client.
Header
X-PaperCode
string
Y
Code that designates the newspaper.
Header
X-SourceSystem
string
Y
Code that designates the application.
Header
Authorization
string
Y
Authorization token.
Header
X-RequestId
integer
Y
Defines where to look for the user. 1 = User Provider; 2 = Naviga's database; 0 User provider and Naviga's database (recommended)
Query string
request.email
string
Y
Email address that is checked.
Query string
request.onlyActive
boolean
Y
If TRUE, only checks active subscriptions. If FALSE, checks both active and inactive subscriptions.
The following is a cURL request example:
The following is a json example response from the /user endpoint:
POST /User - This endpoint creates the user if the user doesn't already exist.
Parameter Type
Parameter
Data Type
Required?
Description
Header
X-MediaGroupCode
string
Y
Code that designates the circulation system.
Header
X-ClientCode
string
Y
Code that designates the client.
Header
X-PaperCode
string
Y
Code that designates the newspaper.
Header
X-SourceSystem
string
Y
Code that designates the application.
Header
Authorization
string
Y
Authorization token.
Header
X-RequestId
integer
Y
Defines where to look for the user. 1 = User Provider; 2 = Naviga's database; 0 User provider and Naviga's database (recommended)
Request body
integer
Y
JSON object (see request example below).
The following is a cURL request example:
The following is a json example response from the /User endpoint:
GET /Address/Standardization - this endpoint uses a service to standardize the entered address.
Parameter Type
Parameter
Data Type
Required?
Description
Header
X-MediaGroupCode
string
Y
Code that designates the circulation system.
Header
X-ClientCode
string
Y
Code that designates the client.
Header
X-PaperCode
string
Y
Code that designates the newspaper.
Header
X-SourceSystem
string
Y
Code that designates the application.
Header
Authorization
string
Y
Authorization token.
Header
X-RequestId
integer
Y
Defines where to look for the user. 1 = User Provider; 2 = Naviga's database; 0 User provider and Naviga's database (recommended)
Query string
request.address.address
string
Y
Street address that is checked.
Query string
request.city
string
Y
City of address that is checked.
Query string
request.state
string
Y
State of address that is checked.
Query string
request.postalCode
number
Y
Postal code of address that is checked.
The following is a cURL request example:
The following is a json example response from the /Address/Standardization endpoint:
POST /Subscription/ActiveCheck - this endpoint checks the subscriber has an active subscription
Parameter Type
Parameter
Data Type
Required?
Description
Header
X-MediaGroupCode
string
Y
Code that designates the circulation system.
Header
X-ClientCode
string
Y
Code that designates the client.
Header
X-PaperCode
string
Y
Code that designates the newspaper.
Header
X-SourceSystem
string
Y
Code that designates the application.
Header
Authorization
string
Y
Authorization token.
Header
X-RequestId
integer
Y
Defines where to look for the user. 1 = User Provider; 2 = Naviga's database; 0 User provider and Naviga's database (recommended)
Request body
integer
Y
JSON object (see request example below).
The following is a cURL request example:
The following is a json example response from the Subscriptions/ActiveCheck endpoint:
POST /Billing/PaymentSession/StartPaymentSession
Parameter Type
Parameter
Data Type
Required?
Description
Header
X-MediaGroupCode
string
Y
Code that designates the circulation system.
Header
X-ClientCode
string
Y
Code that designates the client.
Header
X-PaperCode
string
Y
Code that designates the newspaper.
Header
X-SourceSystem
string
Y
Code that designates the application.
Header
Authorization
string
Y
Authorization token.
Header
X-RequestId
integer
Y
Defines where to look for the user. 1 = User Provider; 2 = Naviga's database; 0 User provider and Naviga's database (recommended)
Request body
integer
Y
JSON object (see request example below).
The following is a cURL request example:
The following is a json example response from the /Billing/PaymentSession/StartPaymentSession endpoint:
POST /Billing/PaymentSession/EndPaymentSession
Parameter Type
Parameter
Data Type
Required?
Description
Header
X-MediaGroupCode
string
Y
Code that designates the circulation system.
Header
X-ClientCode
string
Y
Code that designates the client.
Header
X-PaperCode
string
Y
Code that designates the newspaper.
Header
X-SourceSystem
string
Y
Code that designates the application.
Header
Authorization
string
Y
Authorization token.
Header
X-RequestId
integer
Y
Defines where to look for the user. 1 = User Provider; 2 = Naviga's database; 0 User provider and Naviga's database (recommended)
Request body
integer
Y
JSON object (see request example below).
The following is a cURL request example:
The following is a json example response from the /Billing/PaymentSession/EndPaymentSession endpoint:
POST /Subscriptions - this endpoint creates the subscription after the user selects to submit the order
Parameter Type
Parameter
Data Type
Required?
Description
Header
X-MediaGroupCode
string
Y
Code that designates the circulation system.
Header
X-ClientCode
string
Y
Code that designates the client.
Header
X-PaperCode
string
Y
Code that designates the newspaper.
Header
X-SourceSystem
string
Y
Code that designates the application.
Header
Authorization
string
Y
Authorization token.
Header
X-RequestId
integer
Y
Defines where to look for the user. 1 = User Provider; 2 = Naviga's database; 0 User provider and Naviga's database (recommended)
Request body
integer
Y
JSON object (see request example below).
The following is a cURL request example:
The following is a json example response from the /Subscriptions endpoint:
This is the standard flow that our clients usually implement in their Apps.
The Store knows if you already had bought a subscription in that Store.
The GET User call returns the customer registration ID if a user with that email already exists. If a customer doesn’t, use the CreateUser endpoint.
There’s no need to validate if the email has a Naviga's subscription already – with unlimited digital access for instance - because we have to insert the InApp subscription anyway. In this last scenario, if the user cancels the Naviga's one in the future, the will still have digital access using the inApp subscription.
The GetUser / CreateUser call can be done after purchasing in the Store, buit before the CreateSubcription call.
The GetsubscriptionsByCustomerRegistrationId endpoint here for good measure.
GET
api/User/{type}?email={email}
This endpoint gets users account by using the user's email address.
Parameter Type
Parameter
Data Type
Required
Description
HEAD
Authorization
String
Y
Endpoint's authorization.
HEAD
X-SourceSystem
String
Y
HEAD
X-MediaGroupCode
String
Y
HEAD
X-ClientCode
String
Y
HEAD
X-PaperCode
String
Y
QUERY_STRING
String
Y
Unique identifier of the User in Naviga's system.
URL_PARAM
Type
Number
Y
Defines where to look for the user. 1 = User Provider; 2 = Naviga's database; 0 User provider and Naviga's database (recommended)
The following is a cURL request example for the endpoint.
The following is a JSON example of a successful response from the api/User/{type}?email={email} endpoint:
Naviga's API attempts to return appropriate HTTP status codes for every request.
Status Code
Response
400
{"error":"Authorization is missing."}
400
{"error":"X-SourceSystem is missing."}
400
{"error":"request cannot be null."}
401
{"error":"Invalid Authorization."}
401
{"error":"Invalid X-SourceSystem."}
500
{"error":"Something went wrong. Please try again later."}
POST
api/User
This endpoint creates a user.
Parameter Type
Parameter
Data Type
Required
Description
HEAD
Authorization
string
Y
HEAD
X-SourceSystem
string
Y
HEAD
X-MediaGroupCode
string
Y
HEAD
X-ClientCode
string
Y
HEAD
X-PaperCode
string
Y
BODY
string
Y
BODY
Password
string
N
BODY
CreationMode
number
Y
Defines where to create the user. 1 = User provider; 2 = Naviga's database; 0 = both (highly recommended)
BODY
CustomerRegistrationId
string
N
BODY
FirstName
string
N
BODY
LastName
string
N
BODY
PhonaAc
string
N
BODY
PhoneEx
string
N
BODY
PhoneExt
string
N
BODY
MobilePhone
string
N
BODY
DOB
string
N
BODY
BirthYear
string
N
BODY
Gender
string
N
BODY
OptInEVantageSubscriberRewards
boolean
N
BODY
OptInSpecialOffers
boolean
N
BODY
OptInContestAndPromotions
boolean
N
BODY
OptInPaperlessBilling
boolean
N
BODY
OptInEEdition
boolean
N
BODY
OptInEEditionEmailNtification
boolean
N
BODY
OptInSubscriberDiscounts
boolean
N
BODY
OptInAdvertiserEmails
boolean
N
BODY
MemberEvent
boolean
N
BODY
ContentEngagement
boolean
N
BODY
SUBCOM
boolean
N
BODY
Survey
boolean
N
BODY
AccountUpdates
boolean
N
0-255
BODY
AcceptsEmailOffers
number
N
0-255
BODY
AcceptsEmailAds
number
N
0-255
BODY
AcceptsEmailPromotions
number
N
0-255
BODY
IsOkToEmail
number
N
0-255
BODY
IsOkToPhone
number
N
0-255
BODY
IsOkToMail
number
N
0-255
BODY
AcceptsEENtification
number
N
BODY
AcceptsTermsOfService
boolean
N
BODY
Photo
string
N
BODY
OptOutMarketing
boolean
N
BODY
VerifyEmail
boolean
Y
The following is a cURL request example for the endpoint.
The following is a JSON example of a successful response from the api/User endpoint:
Naviga's API attempts to return appropriate HTTP status codes for every request.
Status Code
Response
400
{"error":"Authorization is missing."}
400
{"error":"X-SourceSystem is missing."}
400
{"error":"request cannot be null."}
401
{"error":"Invalid Authorization."}
401
{"error":"Invalid X-SourceSystem."}
500
{"error":"Something went wrong. Please try again later."}
GET
/users/{12345}/subscriptions/?CustomerRegistrationId={1234}5&paperCodesAllowed=JCO,JCOE
This endpoint gets the active subscriptions of a customer using the customer's registration ID.
Parameter Type
Parameter
Data Type
Required
Description
HEAD
Authorization
string
Y
HEAD
X-SourceSystem
string
Y
HEAD
X-MediaGroupCode
string
Y
HEAD
X-ClientCode
string
Y
HEAD
X-PaperCode
string
Y
URL_PARAM
customerRegistrationId
string
Y
The unique identifier of a customer in Naviga. Also known as Customer Registration Id. Represents an user.
URL_PARAM
paperCodesAllowed
string
N
Set of paper codes allowed for the subscription's lookup.
URL_PARAM
includeStoppedSubscriptions
boolean
N
Determines whether the response includes stopped subscriptions.
The following is a cURL request example of the endpoint.
The following is a JSON example of a successful response from the /users/12345/subscriptions/?CustomerRegistrationId=12345&paperCodesAllowed=JCO,JCOE endpoint:
Naviga's API attempts to return appropriate HTTP status codes for every request.
Status Code
Response
400
{"error":"Authorization is missing."}
400
{"error":"X-SourceSystem is missing."}
400
{"error":"request cannot be null."}
401
{"error":"Invalid Authorization."}
401
{"error":"Invalid X-SourceSystem."}
500
{"error":"Something went wrong. Please try again later."}
The app calls Naviga API to create subscription. Try out the API with the Swagger link below:
The minimum required values for Naviga 2.x:
The minimum required values for Naviga 3.x:
The iTunesInfo below is the complete response from iTunes purchase response (see the examples).
The client should provide the Credentials for the Store – Test and Prod instance. The credentials for iTunes and Google are stored in mg2_control settings:
Apple.VerifySecret (iTunes)
ExternalPaymentWebhook.AuthToken (GooglePlay)
The app can also call Naviga's API to get an offer instead of storing the offer and promotion id. Please reach out to Naviga for more details.
The client can pass more details in add subscription call. Please find below json details below:
To maintain the subscription status, push notifications must be sent to the following endpoint for Google Play and iTunes:
https://prod.subscriberconcierge.com/Notifications/{provider}/{mediaGroup}/{clientCode}/{paperCode}
The provider would be one of the following:
iTunes
GooglePlay
Please reach out to your PM for your specific MediaGroup, ClientCode & Papercode settings.
Once you have received your push notification endpoints, the client must follow the documentation below to setup these up in their GooglePlay or iTunes console. Please refer to the following documentation.
Google Notifications leverages the use of Google Cloud Pub/Sub. See the following link to configure the Topics and Subscriptions:
https://developer.android.com/google/play/billing/getting-ready
Subscribe exposes an endpoint to receive the notifications at any time. This means that the Subscription needs to be configured as a Push.
https://cloud.google.com/pubsub/docs/push
NOTE: Originally, Google requested for confirmation on domain ownership by generating a unique confirmation file to be installed on the servers. Google has discontinued this.
MG2Control setting: ExternalPaymentWebhook.AuthToken
Supported notifications:
SUBSCRIPTION_CANCELED
SUBSCRIPTION_DEFERRED
SUBSCRIPTION_ON_HOLD
SUBSCRIPTION_PRICE_CHANGE_CONFIRMED
SUBSCRIPTION_RECOVERED
SUBSCRIPTION_RENEWED
SUBSCRIPTION_RESTARTED
NOTE: All notifications except s
ubscription_canceledandsubscription_restartedare ignored by Naviga in Google Play.
Mg2Control setting: Apple.VerifySecret
NOTE: In iTunes, only
cancel,interactive_renewal, anddid_change_renewal_prefare processed by Naviga. The remaining are ignored.
To maintain subscription status, Naviga has created a nightly process that calls Amazon and updates Subscribe db. For each active ReceiptId, the process sends a verification request through the Amazon API. In response to the verification request, the subscription status is active, canceled, or restarted in Naviga.
Clients will have to configure ClientId and ClientSecret in the Amazon developer console: https://developer.amazon.com/ (Settings -> Security Profile) https://prnt.sc/rhyrdf so Naviga can access Amazon API.
Mg2Control settings: Amazon.ClientId and Amazon.ClientSecret
For versions 3.9+, we introduced a new event type VERIFYCODECONFIRMATION (671), that needs to have active = 1 and triggers_post = 1, and associated with Event Processor = ExternalPayments (27), in order to work.
The advantage of this new Start child event is to provide more information about the responses we get from Markets (iTunes, Google, etc.) on the Confirmation Receipt call. In the event_post_return_html table, you can see the responses from those.
Scripts to do the update in case it’s not set up:
Update NewspaperEventProcessorAssignments Set EventProcessorId = 27 where EventTypeId = 671
UPDATE event_types SET triggers_post = 1, active = 1 where event_type_id = 671
