SBB Mobile Deep Linking.
Version: September 2016
Author
SBB
Document name
SBBmobile_DeepLiniking.docx
Version
0.8
Creation date 18.03.2016
Document status
In progress
Change date 21/10/2016
Confidentiality
Open
Swiss Federal Railways SBB
www.sbb.ch
Version 0.8
Page 2/9
Version
Date
Implementing entity
Notes / Type of change
0.1
18/03/2016
R. Neu
0.2
21/03/2016
R. Neu
0.3
0.4
0.5
0.6
0.7
0.8
23/03/2016
30/03/2016
19/04/2016
04/05/2016
R. Neu
R. Neu
R. Neu
R. Neu
R. Neu
R. Neu
Derivation of the URL schema of the initial SBB
mobile app.
Incorporation of feedback from M. Fetzer and
R. Wetzel
Tripticket renamed and recon Base64
Correction of Custom Scheme
System notifications
Display ticket list
09/09/2016
Swiss Federal Railways SBB
www.sbb.ch
Support for legacy parameters (with deprecated
highlighted). AccessId definitively removed.
Sbbmobileb2c:// will be supported from
01/11/16. AppId attached to all requests
Version 0.8
Page 3/9
Contents
1.
General information ................................................................................................ 4
2.
2.1.
2.2.
Timetable enquiries ................................................................................................ 4
URL structure and parameters .................................................................................. 4
Parameter ................................................................................................................. 4
3.
3.1.
3.2.
Displaying connections .......................................................................................... 5
URL structure and parameters .................................................................................. 5
Parameter ................................................................................................................. 5
4.
4.1.
4.2.
Loading ticket offers for specific connection ....................................................... 6
URL structure and parameters .................................................................................. 6
Parameter ................................................................................................................. 6
5.
5.1.
5.2.
Displaying tickets ................................................................................................... 7
URL structure and parameters .................................................................................. 7
Parameter ................................................................................................................. 7
6.
6.1.
6.2.
Displaying ticket lists ............................................................................................. 7
URL structure and parameters .................................................................................. 7
Parameter ................................................................................................................. 7
7.
7.1.
7.1.1.
7.1.2.
7.1.3.
Callback system notification .................................................................................. 8
Purchase system notification .................................................................................... 8
Required interface of the third-party system to be called ........................................... 8
Parameter ................................................................................................................. 8
Security..................................................................................................................... 9
Swiss Federal Railways SBB
www.sbb.ch
Version 0.8
Page 4/9
1.
General information
-
Deep Linking means calling up an app using a URL. The schema and host of the URL specify
which app is to be opened. The path and the parameters of the URL can be used to transfer
data to the application. The schema-host combination is referred to simply as the schema below for the sake of simplicity.
-
The following deep links are supported; however the https://app.sbbmobile.ch variants have
priority
-
http schema (only for shortlinks)
http://a.sbbmobile.ch/
https schema
https://app.sbbmobile.ch/
Custom schema
sbbmobile://
Custom schema (from 1/11/16, deprecated)
sbbmobileb2c://
All URL parameters must be encoded with UTF-8 (in accordance with RFC-3986 "Percent Encoding").
-
Empty parameters are ignored
-
The schema must be adjusted in order to work with test apps
For DEV:
https://appdev.sbbmobile.ch
and sbbmobiledev://
For TEST:
https://apptest.sbbmobile.ch
and sbbmobiletest://
For INTEGRATION:
https://appint.sbbmobile.ch
and sbbmobileint://
2.
Timetable enquiries
2.1.
URL structure and parameters
<Schema>timetable?<Parameter>
<Schema>ticket?<Parameter> (deprecated)
<Schema>reservation?<Parameter> (deprecated)
2.2.
Name
Parameter
Type
Description
From version
Optional,
iOS/Android
Default
from
String
Departure stop, address or POI
--/0.1.32
to
String
Arrival stop, address or POI
--/0.1.32
Swiss Federal Railways SBB
www.sbb.ch
Version 0.8
Page 5/9
fromll
String
Departure WGS84 coordinates
toll
String
Arrival WGS84 coordinates
via
String
Deprecated. First via stop
via0
String
First via stop
--/0.1.32
via1
String
Second via stop
--/0.1.32
via2
String
Third via stop
--/0.1.32
time
Timestamp
Date and time of the desired departure or arrival.
--/0.1.32
(UNIX)
traveldate
yyyy-MM-dd
Deprecated. Date of desired departure or arrival.
traveltime
HH:mm
Deprecated. Time of desired departure or arrival.
timemode
Enum
Information on whether the time given refers to
[departure,arrival]
departure or arrival.
String
A reference for this call that identifies the app/system to
appid
--/0.1.32
--/0.1.36
be called. It is recommended that the application Id
(Android app), bundle identifier (iOS app) or FQDN
(website) is used.
3.
Displaying connections
3.1.
URL structure and parameters
<Schema>trip?<Parameter>
3.2.
Name
recon
date
appid
Parameter
Type
Description
String
The Hafas reconstruction context for defining a
(Base64)
connection.
Date
The date on which the referenced connection should be
(yyyy-MM-dd)
looked for.
String
A reference for this call that identifies the calling
From version
Optional,
iOS/Android
Default
--/0.1.32
--/0.1.32
app/system. It is recommended that the application Id
Swiss Federal Railways SBB
www.sbb.ch
Version 0.8
Page 6/9
(Android app), bundle identifier (iOS app) or FQDN
(website) is used..
4.
Loading ticket offers for specific connection
4.1.
URL structure and parameters
<Schema>tripoffer?<Parameter>
4.2.
Name
recon
date
Parameter
Type
Description
String
The Hafas reconstruction context for defining a
(Base64)
connection.
Date
The date on which the referenced connection should be
(yyyy-MM-dd)
looked for. This date overwrites the existing date in the
From version
Optional,
iOS/Android
Default
--/0.1.32
--/0.1.32
Hafas reconstruction context.
class
Enum
Pre-selection of the desired travel class.
--/0.1.32
optional
Pre-selection of the desired travel type.
--/0.1.32
Optional,
[1,2]
travel
Enum
[oneway,return]
Default =
oneway
fare
lock
Enum
Information on whether the half-tax price or the full price --/0.1.32
Optional,
[half,full]
should be displayed. If this parameter is not entered, the
Default =
preference saved in SBB mobile vNext is used.
full
Boolean
Information on whether the selected connection can be
--/--
Optional
[true,false]
adjusted (display alternative supersaver tickets,
Default =
automatically adjust time for a combination ticket). True
false
means that the connection may not be adjusted.
ref
appid
String
String
An optional reference for this call that can be defined by --/0.1.36
Optional,
the calling app/system. (Only relevant if a system with
Default =
this reference is to be notified following purchase)
null
A reference for this call that identifies the calling
--/0.1.36
app/system. It is recommended that the application Id
Swiss Federal Railways SBB
www.sbb.ch
Version 0.8
Page 7/9
(Android app), bundle identifier (iOS app) or FQDN
(website) is used.
returnurl
String (Base64)
An optional in-app URL that can be called in order to
0.2.?/--
Optional
navigate back to the caller. If this value is not entered,
Default =
no back button is displayed. This parameter is only
null
supported on iOS, with Android the same function is
performed by the system back button. Parameters are
not supported and are always received via the callback
system notification.
appid
String
A reference for this call that identifies the calling
app/system. It is recommended that the application Id
(Android app), bundle identifier (iOS app) or FQDN
(website) is used.
5.
Displaying tickets
5.1.
URL structure and parameters
<Schema>ticketdetail?<Parameter>
5.2.
Name
Parameter
Type
Description
ticketid
String
DRAFT: Reference of the ticket to be displayed.
appid
String
A reference for this call that identifies the calling
From version
Optional,
iOS/Android
Default
--/--
app/system. It is recommended that the application Id
(Android app), bundle identifier (iOS app) or FQDN
(website) is used.
6.
Displaying ticket lists
6.1.
URL structure and parameters
<Schema>ticketlist<Parameter>
6.2.
Parameter
Not required
Swiss Federal Railways SBB
www.sbb.ch
Version 0.8
Page 8/9
7.
Callback system notification
In addition to calling the app via deeplink, an option is provided whereby the SBB mobile
vNext app notifies a defined system for specific actions using an https request in accordance
with the callback principle. A call can be carried out multiple times if there are multiple values
to be transferred. The reply of the system called is not taken into account. This notification is
only sent to SBB partners that are included in the backend configuration on the basis of a
contract.
7.1.
Purchase system notification
When the URL with the path "tripoffer" is called, if the parameter "appid" is also given and
SBB mobile is recognised, a stored URL is called with PUT:
7.1.1. Required interface of the third-party system to be called
PUT https://<url>/<ref>/<dossierid>
Header
Authorisation: Basic BASE64(appid:sharedkey)
7.1.2. Parameter
Name
Type
url
String
Description
The URL to be called, without specifying the protocol.
From version
Optional,
iOS/Android
Default
--/0.1.36
SBB must be provided with this when the contract is
concluded, and SBB then stores it in the backend
system.
ref
String
A reference to the call of the "tripoffer" deep link. The
--/0.1.36
parameter corresponds to the value ref, and deep links
Default =
are transferred when "tripoffer" is called.
empty
dossierid
String
A reference to the purchased ticket.
appid
String
The app id of the calling app/system as it was submitted --/0.1.36
--/0.1.36
to SBB when the contract was concluded and how it
must be transferred for each call.
sharedkey
String
Der sharedKey of the calling app/system as it was
--/0.1.36
submitted to SBB when the contract was concluded
including app ID and URL.
Swiss Federal Railways SBB
www.sbb.ch
Optional,
Version 0.8
Page 9/9
7.1.3. Security
The interface to be called is called exclusively via https and no http redirects are followed.
The certificate issuer for the provided endpoint must be communicated to SBB when the contract is concluded. Any change to the certificate must be notified 30 days in advance.
Swiss Federal Railways SBB
www.sbb.ch
Version 0.8