EXCHANGE BROKER UTILITY

How to consume the eXchange Broker Utility - Consumer Document 

 

In order to get a secured deep link, the consumer needs to call the eXchange Broker Utility. The eXchange Broker Utility is a technical utility that enables parties outside of the Aviato platform to create deep links into the platform. Deep links created by this utility support the transfer of sensitive data through tokenization. Other features include configuring Time To Live for deep links and configuring a number of times a deep link can be used.

The main objective of eXchange Broker Utility is to provide a mechanism to support consumers to exchange safe URL’s containing sensitive data, and by that enabling the reuse of BlueWeb UBCs, achieving SSO between Mobile and BlueWeb and securely passing data between other touch points.

Getting Started

There are three categories of users in the Broker Utility:

  • customer: represent the user, the one that calls the deep link
  • Consumers: Represents the teams that want to consume the Broker Utility
  • UBC: Represents the team in where the deep link URL ends up

There are two flows using the Broker Utility:

  1. Creating the secured deep link and
  2. Consuming the deep link.

To create the deep link, data is sent by the consumer to the Broker Utility via a POST call. The data that is sent to the Broker Utility is stored securely. After storage of the data, the consumer will receive directly a secured deep link. This deep link can be used to go to the targeted UBC. When the deep link URL is called, the Broker Utility will decrypt the information and sends the customer together with the stored data to the UBC. When action is finished the customer is redirected to the succes-url which will be defined in the data (that is stored by the creation of the deep link) by the consumer. 

 

Creating a deep link

Below the steps are described exactly on how to create a deep link URL via the Broker Utility. In short, to create the deep link the following steps should be followed: 

  1. Consumer calls a POST request to https://api<-env>.airfranceklm.com/deeplinkbroker/deeplink?api_key={{api_key}}&sig={{sig}}and in the body the data that needs to be transferred to the UBC
  2. The Broker Utility stores the transfer data in the Mongo DB
  3. Mongo DB sends an ID for the stored data back to Broker Utility
  4. Broker Utility encrypts the ID in a deep link URL
  5. Broker Utility sends the deep link URL to the consumer

When the consumer has received the deep link URL, This deep link can be used to go to the targeted UBC. 

Be aware that in order to use the Broker Utility, authentication via Mashery is required. 

Creating new deep link 

To create a new deep link URL the following POST request can be called:

POST  https://api<-env>.airfranceklm.com/deeplinkbroker/deeplink

Where <env> should be replaced with targeted environment, for {{api_key}} and {{sig}} fill in your authentication via Mashery if on root level, if behind travel, please provide oAuthToken for authentication. The above URL can be used with the body in where the transfer data is stored. On how the data model of the body looks like is explained below.

Be aware that some keys are mandatory in order to successfully consume the deep link URL. The data that needs to be stored can be placed in the object "target_data", which is a free data object. The data model that is needed in the body of the POST request looks like the following:

{
        "interaction_method": "online", 
        “distribution_type": “direct", 
        "target_segment": "B2C", 
        "interaction_channel_type": "web", 
        "touchpoint_id": "blueweb",
        "target": "payment_lounge", 
        "country": "NL", 
        "brand": “KL", 
        "language": "nl", 
        
        "target_data": { 
               "sessionId": "as32jh342kj34" // Needed only when SSO needs to be maintained
               "engineId": "098asdf98asdf"//  Needed only when SSO needs to be maintained
               // + all desired data that needs to be stored
               // + all data that is needed to set up a successful session
               
        },
        "ttl": 600000, 
        "max_invocations": 3 
}

.

The keys that are used in the data model are explained as:

Key              

Possible value

Explanation

Mandatory?

“Interaction_method”

“online”

“offline”

 

“distribution_type”

direct

indirect

“interaction_channel_type”

web

phone

“app”

“email”

“chatbot”

“searchengines”

“face2face”

Interaction channel

"touchpoint_id"

"blueweb"

....

....

An optional alternative “touchpoint definition”.

This touchpoint definition is based on context model if not used

“target_segment”

“B2C”

“B2E”

“B2T”

“B2B”

Type of segment


“target”

payment

checkin

...

The target destination user needs to go to, e.g. the payment page.

Y

“target_data”

Data object that can be transported 1 on 1 to the target, without modifying.

Free data object. 

“country”

Please check Migration domains setup for Aviato 

for the supported countries conform ISO 3166-1 alpha-2.

The country code is required for all touchpoints conform ISO 3166-1 Alpha-2.

The country code is needed for BlueWeb to set up a session.

Any country code that BW supports can be used.

“brand”

AF

KL

Brand (KL or AF), needed for BlueWeb to set up a session with correct layout. 

language

Please check Migration domains setup for Aviato 

for the supported languages conform ISO 639-1

Optional passing of the language conform ISO 639-1.

 If the language filled in is not recognized for the filled-in country,

the default language of the country will be used

success_url

The URL where the customer needs to be redirected when action was successful

(e.g. payment succeeded).

Please contact the UBC to discuss the desired flow and if this key is needed

failed_url

The URL where the customer needs to be redirected when action has failed

(e.g. payment declined). 

Please contact the UBC to discuss the desired flow and if this key is needed

cancelled_url

The URL where the customer needs to be redirected when action was cancelled

(e.g. payment cancelled). 

Please contact the UBC to discuss the desired flow and if this key is needed

Other target data

All keys that needs to be stored and send with the deep link e.g. PNR, lastName

ttl

Time-to-live, the time in seconds that the secured deeplink is valid.

If not mentioned the information will be stored in for period of 6 MONTHS

Max_invocations

Maximum number that the secured deep link can be called within the ttl.

If not mentioned, the deep link can be called

In the body in the object "target_data” the consumer is able to store all desired data. For the Broker Utility it does not matter what and how much data there is stored in this object. However, please be aware that each UBC (the touchpoint of the deep link URL) require different keys in order to set up a successful session. In Customers (planned for migration) the keys required for each UBC can be found. Make sure that at least these required keys are in the object “target_data”, together with the mandatory keys as explained in the table above.

For example: If the consumer wants to deep link the user to BW Check-out to finalize the payment the data model will look like the following:

Sample POST Request 

POST /travel/deeplinkbroker/deeplink/
 
{
    "interaction_method""online",
    “distribution_type": “direct",
    "target_segment""B2C",
    "interaction_channel_type""web",
    "touchpoint_id""blueweb",
    "target""payment",
    "country""NL",
    "brand""KL",
    "language""nl",
    "target_data": {
        "success_url""https://example.klm.com/payment-success",
        "failed_url""https://example.klm.com/payment-failed",
        "cancelled_url""https://example.klm.com/payment-cancelled",
        "PNR""WJHKUZ",
        “first_name": "Jan",
        “last_name": "de Vries",
        "amount""450.60",
        “currency”: “euro”,
        "identifier""Lounge" // pass the consumer name
    },
    "ttl"600000,
    "max_invocations"3
}

 

Sample POST Response

{
"deeplink": “https://www.klm.nl/exchange/inbound?target_id=54759eb3c090d83494e2d804”,
“target_id": "54759eb3c090d83494e2d804",
"ttl"600000,
"max_invocations"3
}

If the consumer wants get a deeplink to BW Check-out to finalize the payment the request and response of the GET call will look like the following:

Sample GET Request  

GET /deeplinkbroker/deeplink/{deeplinkId}

Sample GET Response

{
    "interaction_method""online",
    “distribution_type": “direct",
    "target_segment""B2C",
    "interaction_channel_type""web",
    "touchpoint_id""blueweb",
    "target""payment",
    "country""NL",
    "brand""KL",
    "language""nl",
    "target_data": {
        "success_url""https://example.klm.com/payment-success",
        "failed_url""https://example.klm.com/payment-failed",
        "cancelled_url""https://example.klm.com/payment-cancelled",
        "PNR""WJHKUZ",
        “first_name": "Jan",
        “last_name": "de Vries",
        "amount""450.60",
        “currency”: “euro”,
    },
    "ttl"49000,
    "max_invocations"2
}

Error handling 

Status Code

200 (OK)
400 (BAD REQUEST)
401 (UNAUTHORIZED)
404 (NOT FOUND) > token not found?
410 (GONE) > Token has expired?
500 (INTERNAL SERVER ERROR)

 

Consuming a deep link

 

Once the user clicks on the deep link URL (that is created in 1. Creating a deep link) the user is directed via the Exchange to the Broker Utility. The Broker decrypts the information and sends the user with their sensitive data to the UBC. From here the UBC can find all the information needed to set up a session. When the action is completed, the UBC redirects the user to their origin.

Below the steps are described exactly on what the consumer or UBC needs to do in order to consume the deep link URL and to redirect the user to their origin. In short, to consume the deep link the following steps should be followed: 

  1. Consumer calls deep link URL and sends to Exchange
  2. Exchange sends user with ID to Broker Utility
  3. Broker Utility decrypts deep link URL and gets transfer data from the Mongo DB
  4. Broker Utility stores data in Redis and sets the transfer data in the session data
  5. UBC retrieves information in session data in the object {broker} 
  6. If action is completed the UBC sends user back to consumer

Call Deep link URL 

To consume the deep link URL, just call the deep link URL via a GET request. Then the user will be redirected to the Broker Utility. The Broker Utility decrypts the deep link URL, gets the ID and retrieves the transfer data from the Mongo DB. This transfer data is stored into the session data, after that the Broker Utility sends the user to the targeted UBC. 

GET: https://api<-env>.airfranceklm.com/deeplinkbroker/deeplink/{{deeplink_id}}?api_key={{api_key}}&sig={{sig}}

Get Session data 

The UBC will receive the data from the Broker Utility in the session data with all the information needed in order to set up a session. In the session data the object “{broker}” can be found. In this object all the target data that is sent by the consumer can be found.

Example session data 

{      

    broker: {
         "_id""5d512b5ac311bc0028asdf",
         "expires""2019-08-12T09:13:22.000Z",
         "touchpoint""bw",
         "target""payment",
         "target_data": {
              "country""nl",
              "language""nl",
              "brand""KL",
              "success_url""https://example.com/payment-success",
              "failed_url""https://example.com/payment-failed",
              "cancelled_url""https://example.com/payment-cancelled",
              "PNR""WJHKUZ",
              "firstname""Jan",
              "lastname""de Vries",
              "amount""450.60"
             // + all other data that are sent
            },
         "max_invocations"3
        }
}

Redirect to Origin

When the action is completed, the user gets redirected to where the user came from. This redirection is done by the UBC, not by the Broker Utility.

As a consumer, please contact the UBC and discuss the desired flow, so the UBC is prepared for the flow the consumer wants.

 

Consumer FAQ

General questions:

What are the keys mandatory to be stored in the deep link for Checkout?
These are: PNR, First name, Last name, Market, Channel
Why are keys “language”, “country” and “brand” mandatory?
These keys are needed to set up a valid session in BlueWeb 

Questions about “Touchpoint”:

What is the value for “touchpoint”?
To end up in BlueWeb, fill in: “BW”

Questions about “Target”:

What is the target to end up in BW Checkout?
To end up in Checkout fill in: “payment”

Questions about “Brand”:

Why is Brand mandatory?
Blueweb needs to know the airline in order to show the correct layout.
What are the codes to fill in?
"AF" for Air France
"KL" for KLM

Questions about “Country”:

What are the countries supported by BlueWeb
The countries that are supported can be found on the following Confluence page: Domains in use by BlueWeb
If a country is filled in that is supported by Blueweb, what happens then?
If the filled-in country is not supported you will be routed back to www.klm.nl (for KLM) or www.airfrance.fr(for Air France)

Questions about “Language”:

What are the languages supported by Blueweb for country X?
The languages that are supported for specific countries can be found on the following Confluence page: Domains in use by BlueWeb
What if the language filled in is not supported for the country filled in?
Then, the default language for the country filled in will be used.

Questions about “ttl”:

Is ttl mandatory?
It is not mandatory to fill in a ttl. If not mentioned the information will be stored in for period of six months
What is the unit for ttl?
The time to fill in will be in milliseconds.
Is it possible to set a fixed time for ttl? 
No, it is not possible to set the ttl at a fixed time, e.g. a few hours before departure date.  The time you enter in ttl will always be a relative time, in milliseconds.
Of course, you can calculate how many milliseconds pass until the fixed time you want, but the Restful Service will not do this for you.

Questions about “Max_invocations”:

What does max_invocations mean?
Max_invocations means the number of clicks provided.
<span style="font-size: 12px; white-space: normal;">
</span>

Docs Navigation