To have a complete set of features with data management and views, we recommend using our Native Mobile SDKs for iOS or Android:

Mobilitybox Ticketing SDK General Idea

This chapter explains how to implement coupon activation and show a ticket without Mobilitybox SDK. MobilityBox SDK provides two main functionalities for ticketing:

1. Activate a Coupon

The activation step is where the person buying the ticket enters their personal identification information (i.e., phone number, passport, last four cc, etc.).
You can use it to display an identification form for the user with the coupon ID you received when they bought it.

The form is generated and validated automatically.

2. Displaying the Ticket on the user's phone

When the coupon gets activated in the background, the actual ticket gets generated and ready to be fetched by the user's phone, where it can be displayed for ticket inspection. (Note: At this point, we deleted the uploaded ticket from our servers.)

The SDK fetches the required ticket data and builds a provider-defined ticket inspection view with our rendering engine.

Mobilitybox Identification View

The Identification View displays a form where the user enters his personal information to activate the coupon.

Background: Each coupon belongs to a product that was ordered. Each of these products contains an Identification Medium Schema. This is a JSON Schema describing which option the user has to identify himself when he wants to activate the coupon, for example, with the last four digits of his credit card.

The Identification View uses this schema to generate a form displaying all options available for that coupon to activate it and get the ticket.

1. Fetch Coupon

The first step is to show that view to fetch the coupon with information about the booked product from the mobilitybox coupon API.

2. Fetch Identification View

The next step is to receive the Identification view HTML String via the API endpoint:

"https://api.themobilitybox.com/v4/ticketing/identification_view/:major?inline=inline"
// Current :major is "1"
// https://api.themobilitybox.com/v4/ticketing/identification_view/1?inline=inline

//redirects to latest:
"https://api.themobilitybox.com/v4/ticketing/identification_view/:major/:minor/:patch?inline=inline"

Note: We recommend that the HTML string is cached in order to avoid download it every time. And before fetching data from the redirection compare the major, minor and patch version with the cached one and only fetch the data if the latest version changed.

3. Display Identification View

After loading the identification view HTML String, you have to pass the encoded identification medium schema JSON string by calling the following javascript:

1. Encode product identification medium schema to JSON string
2. Pass encodedIdentificationMediumSchema to the webview: window.renderIdentificationView(encodedIdentificationMediumSchema)

4. Add Event Listener and Activate Coupon

To handle the user input (cancel and activate), some event listeners could by handy.

// close button:
document.getElementById('close_identification_form_button').addEventListener('click', function(){
    // your code here
    // for example: close the view and get back
})

// activate button:
document.getElementById('submit_activate_button').addEventListener('click', function(){
    const identification_medium = window.getIdentificationMedium()
    // your code here
    // activate coupon with activation api
})

After the user fills out all required fields and clicks the activate button, the coupon is ready to be activated. The result of window.getIdentificationMedium() is the identification medium you must pass to the mobilitybox coupon activation API.

For example: '{"identification_medium":{"credit_card":{"last_4_digits":"1234"}}}'

The result of activation is a mobilitybox ticket ID, which can be used in the next step.

Mobilitybox Ticket Inspection View

The Ticket Inspection View shows all information needed for the public transit control personal to check your ticket. It contains a barcode, ticket details, personal information, and security features.

1. Fetch Ticket

The inspection view uses the ticket data fetched from the mobilitybox ticket API with the ticket id received in the step before and the ticket rendering engine.

2. Fetch Ticket Rendering Engine

The ticket rendering engine is an HTML document fetched also from the mobilitybox API:

Receive Ticket Rendering Engine HTML Document via API endpoint:

"https://api.themobilitybox.com/v4/ticketing/rendering_engine/:major?inline=inline"
// Current :major is "1"
// https://api.themobilitybox.com/v4/ticketing/rendering_engine/1?inline=inline

//redirects to latest:
"https://api.themobilitybox.com/v4/ticketing/rendering_engine/:major/:minor/:patch?inline=inline"

Note: We recommend that the HTML string is cached in order to avoid download it every time. And before fetching data from the redirection compare the major, minor and patch version with the cached one and only fetch the data if the latest version changed.

3. Show Ticket Inspection View

After loading the ticket rendering engine (HTML document) in a webview you have to pass the ticket data by calling the following javascript:

1. Encode ticket data to JSON string
2. Pass encodedTicketData to the webview: window.renderTicket(encodedTicketData)

After passing the data, the webview shows the described information.

Handle Reactivatable Coupons (Subscriptions)

The coupon can be reactivated for the next subscription cycle when a subscription is reordered. You will receive a new ticket valid for the next subscription cycle.

1. Fetch Coupon

To check if the coupon can be reactivated, you can use the coupon ID from your ticket data to retrieve the coupon and subscription data.
The attribute coupon_reactivatable of the subscription shows if the coupon is reactivatable.

2. Reactivate Coupon

The next step is to call the coupon activate endpoint and pass the coupon_reactivation_key of the ticket to receive the following ticket ID.

3. Fetch Ticket

With that ticket ID, you can get the new ticket data and display it again with the ticket rendering engine. Additionally, you can repeat the previous steps to check if a reactivation is possible.