Custom URL schemes are a powerful way to control navigation from just about anywhere in your app! This article provides a complete overview of what you can do with the different URL schemes.
1. Navigating to a collection or article
From within your article content, you can use special URL schemes to link to a collection or a particular article within a collection. These can also be used in InDesign content using a Hyperlink, a Web viewer or a Web Overlay Button.
You can use the following scheme:
tp-collection://[target_collection_name]/[target_article_name]The syntax is as follows (always make sure to refer to the collection or article name, not the title):
tp-collection://[collection-name] |
Will link to the first article in a different collection. |
tp-collection://[collection-name]/[article-name] |
Will link to a specific article in a different collection. |
tp-collection://hamburger-menu |
Will open the Hamburger Menu (provided the Hamburger Menu is enabled). |
tp-collection://parent |
Will link to the parent collection of your current article (not supported in the Browser Client). |
tp-collection://root |
Will link to the root collection of your app. |
2. Navigating to an article or page
The links below can also be used in your InDesign content, in a hyperlink, a web viewer or a web overlay. It can be used to go to another article in the same collection.
tp-pagelink://[article_name]If you want to add a link to a particular page in an article in the same collection from within a browse page or article, you can do so creating an HREF like the one below:
tp-pagelink://[article_name]/[page_number]An HTML example would be:
<a href="tp-pagelink://TOC/3">For InDesign content the article name needs to be the name of the InDesign file. So, in case of the example above, the name of the InDesign document would be TOC.indd.
A number of other URL schemes for relative article and page navigation are also available:
tp-next-article:// |
Go to the next article. |
tp-previous-article:// |
Go to the previous article. |
tp-first-article:// |
Go to the first article of the publication. |
tp-last-article:// |
Go to the last article of the publication. |
tp-next-page:// |
Go to the next page. |
tp-previous-page:// |
Go to the previous page. |
tp-first-page:// |
Go to the first page of an article. |
tp-last-page:// |
Go to the last page of an article. |
tp-article-top:// |
Go to the top of a long-page article. |
tp-article-bottom:// |
Go to the end of a long-page article. |
3. Show/hide the toolbar (for InDesign content)
(Available in an InDesign Hyperlink, a Web viewer or a Web Overlay Button)
tp-toolbar://hide |
Hides the toolbar with the Table of Contents icon, and optional sharing and bookmarking icons. |
tp-toolbar://show |
Displays the toolbar with the Table of Contents icon, and optional sharing and bookmarking icons. |
tp-toolbar://toggle |
Toggles the current view, whether visible or invisible. |
4. Show Table of Contents (for InDesign content)
(Available in an InDesign Hyperlink, a Web viewer or a Web Overlay Button)
tp-toc://When the tp-toc:// url is triggered, it will show the Table of Contents dropdown.
5. Downloads overview
(Can be used in e.g. an InDesign hyperlink, a Web Link content item, or an HTML article.)
tp-downloads://If you have an app where (some or all) collections are marked as Monolithic Download, this URL scheme will trigger the display of an overview of the collections that have been downloaded.
5.1. Watch a short 'How to' video…
- The grid & item styles that are used for this collection are defined in your app settings under 'Search / Downloads' (the same styles are used for both the Downloads collection and the Search results).
- Sorting is done by most recent publish date.
Users can also manage the content that has been downloaded: long-pressing the collection icon of the collection brings up a dialog that allows the user to delete the downloaded content. It can always be re-downloaded later.
6. Library overview
The Library feature allows the publisher to include a section where all the free collections for an app user are displayed, i.e. the free, the purchased and the entitled collections. This feature can be used in e.g. an InDesign hyperlink, a Weblink content item or an HTML article.
tp-library://- The grid & item styles that are used for this collection are defined in your app settings under 'Search / Downloads' (the same styles are used for both the Downloads collection and the Search results).
- Sorting is done by most recent publish date.
The Library-feature differs from the Downloads feature as tp-library doesn't show all the offline available (=downloaded) collections. It only shows the for a user freely available collections and this difference should be considered before implementing this feature.
7. Searching
(Can be used in e.g. an InDesign hyperlink, a Web Link content item, or an HTML article.)
To trigger the search-dialog in your app, you use the following url scheme:
| Custom URL Scheme | Function |
|---|---|
|
Shows an empty dialog |
tp-search://[keyword] |
Executes a search-command with the specified keyword |
Example (search for content with the word twixl):
tp-search://twixl- The grid & item styles that are used for the search result are defined in your app settings under 'Search / Downloads' (the same styles are used for both the Downloads collection and the Search results - see above).
8. Paywall & subscriptions
tp-paywall://Enables you to trigger the paywall, showing both purchases and different subscriptions that you have defined.
tp-subscriptions://Lets you trigger the paywall, showing only the different subscriptions you have defined.
tp-restore-purchases://Lets you trigger the 'Restore purchases' functionality.
9. Entitlements
Show the Entitlements sign-in form
tp-entitlements-signin://Triggers the entitlements sign-in form.
Show the Entitlements register form
tp-entitlements-register://
Triggers the entitlements register form. This only works if the entitlements server provides a "register" action. Available in the kiosk info cell - infoCell.html
Get entitlement token
tp-entitlements-get-token://<callback_function>
Get the current entitlement token, passing it as the argument to the callback_function. If no callback function is specified, it will default to twixlKioskOnGetEntitlementToken.
Clear entitlement token
tp-entitlements-clear-token://Clears the entitlements token (can be used for testing purposes).
10. Sending e-mail
Please refer to the article Advanced Mailto hyperlinks to learn how to use the mailto: URL scheme, to send e-mail from your app.
11. Making a phone call
callto:[number] or tel:[number]Allows you to trigger a phone call.
Example:
callto:+32493252577
tel:+3249325257712. Sharing on social media
To trigger the sharing sheet, you use the following url-scheme:
tp-share://13. Going back in Browsing History
This special url scheme can be used in to go back in the browsing history in an app. The syntax is as follows:
tp-history-back://A history will be saved when going though the different content items. This means that if you are in Article1 and you scroll to Article2, if you then press the custom URL tp-history-back:// it will go back to Article1.
The history will be saved when:
- Scrolling horizontally to other content items.
- Scrolling horizontally/vertically to pages of the same content item.
- Going to another content item or collection with a custom url (tp-pagelink://article2, tp-next-article, tp-collection://collection2...)
- Going to different pages in the same content item with a custom url (tp-next-page://, tp-last-page://, tp-first-page://...)
15. Launching an app
It is possible to trigger launching an app from within a Twixl app using the following scheme:
Please note that the implementation is slightly different on iOS vs Android.
- iOS: the URL scheme is the same as the application identifier:
e.g. if the app identifier is com.twixlmedia.myapp -> then the URL to launch the app would be: com.twixlmedia.myapp://
- Android: the URL scheme is the same as the app identifier without the dots, dashes, underscores and all lowercase:
e.g. if the app identifier is com.twixlmedia.myapp -> the URL to launch the app would be: comtwixlmediamyapp://
IMPORTANT NOTE:
This will only work if the app is already installed on the device.
16. Registering a test device for push notifications
tp-register-test-device://
Triggering this custom URL scheme will add the current device to the list of test devices for push notifications. Note that once push notifications for your app has been configured, you'll need to create a new build of your app before you can use this URL scheme. More details here.
17. Launching third-party apps
In this scenario, it depends on the url schemes supported by the app you want to launch. E.g. an app which can be opened using the url scheme com.mycustomapp:// can be launched by simply creating a hyperlink as follows:
<a href="com.mycustomapp://">Launch My Custom App</a>IMPORTANT NOTE:
This will only work if the app has already been installed on the device.
18. Opening a hyperlink in the device browser
tp-open-in-device-browser=1Although in most cases, you want to keep readers in the embedded browser, sometimes you may want to open a link directly in the default browser on the device (e.g. Safari, Chrome, Brave...). A good use case for this is if you want to link to a PDF that you want readers to be able to download.
You can do this by adding this extra parameter to your URL. Available for Hyperlinks.
Example:
The link you want to open is e.g.:
http://www.website.com/file2.pdfWhile just adding this link will open the URL in the embedded app browser, you can also make it open in the default browser on the device by adding the custom URL link. The link becomes:
http://www.website.com/file2.pdf?tp-open-in-device-browser=1When your original link already has a query parameter, you need to change the ? into a & when adding the custom URL link.
Example for a link with a query parameter:
E.g. the link with a query parameter looks like this:
http://www.website.com/file.pdf?id=1To open this link in the default device browser, the custom URL link will be added like this:
http://www.website.com/file.pdf?id=1&tp-open-in-device-browser=119. Open in embedded web browser
tp-open-in-web-browser=1Adding this url parameter to a hyperlink will open the link in the embedded web browser instead of opening inline.
20. Get the device info via JavaScript
Adding the following JavaScript code to your Content Item, Web Viewer, Web Overlay Button, ...
window.location.href = "tp-device-info://";will execute the following JavaScript function:
function twixlOnGetDeviceInfo(deviceUDID, appVersion, appIdentifier, entitlementToken) {
}This then gives you access to the Device UDID, the app version, the app identifier and the entitlement token. You can also customize the name of the function that gets called:
window.location.href = "tp-device-info://myCustomFunctionName";
function myCustomFunctionName(deviceUDID, appVersion, appIdentifier, entitlementToken) {
}SAMPLE FILES:
For more info, see the sample files on this GitHub-page.
21. Custom Variables
Custom variables allow you to set or get one or more variables with the following properties:
- They are saved on the device
- They can be re-used in advanced scripting
A sample scenario is e.g. to store a user preference and change the content based on that variable.
tp-set-custom-vars://tp-get-custom-vars://Example:
tp-set-custom-vars://?name=&product=MORE INFO ABOUT CUSTOM VARS:
Custom Variables rely on Advanced Scripting. For more info about Advanced Scripting and an example, see: