In order to have a full 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 showing a ticket without Mobilitybox SDK. MobilityBox SDK provides two main functionalities for ticketing:

1. Activate a Coupon

Activation step is where the person buying the ticket enters his/her personal identification information (ie phone number, passport, last four cc, ...)
You can use it to display identification form for the user with couponId 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 prepared to be ready to get fetched by the user's phone, where it can be displayed for ticket inspection. (Note: At this point we delete the uploaded ticket from our servers.)

The SDK is used to fetch the required ticket data and build a provider defined ticket inspection view with our rendering engine.

Mobilitybox Identification View

The Identification View displays a form in which the user enters his personal information when he want to activate the coupon.

Background: Each coupon belongs to a product that was ordered. And each of these products contains a Identification Medium Schema. This is a JSON Schema describing which option the user has to identify hisself when he wants to activate the coupon. For example with the last 4 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, is to fetch the coupon with its information about the booked product from the mobilitybox coupon api.

2. Fetch Identification View

Next Step is to receive Identification view HTML String via 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 products 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), there are some event listener that 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 directly the identification medium that you have to 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. Containing 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 a 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)

When a subscription was reordered, the coupon can be reactivated for the next subscription cycle. You will receive a new ticket which is valid for the next subscription cycle.

1. Fetch Coupon

To check if the Coupon is reactivatable you can use the coupon id of your ticket data to fetch 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 next 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 there is a reactivation possible again.