Mobilitybox Ticketing SDKs for iOS and Android
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:
iOS SwiftUI Package Android Kotlin LibraryMobilitybox 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
andpatch
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:
- encode products identification medium schema to json string
- 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
andpatch
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:
- encode ticket data to json string
- 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.