Login

Learning & Support

Documentation

Using custom URL Schemes in your app

Twixl Support Team Updated: - Created :

    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]
    Click to copy

    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]
    Click to copy

    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]
    Click to copy

    An HTML example would be:

    <a href="tp-pagelink://TOC/3">
    Click to copy

    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://
    Click to copy

    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://
    Click to copy

    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://
    Click to copy
    • 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

    tp-search://

    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
    Click to copy
    • 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://
    Click to copy

    Enables you to trigger the paywall, showing both purchases and different subscriptions that you have defined.  

    tp-subscriptions://
    Click to copy

    Lets you trigger the paywall, showing only the different subscriptions you have defined.

    tp-restore-purchases://
    Click to copy

    Lets you trigger the 'Restore purchases' functionality.

    9. Entitlements

    Show the Entitlements sign-in form

    tp-entitlements-signin://
    Click to copy

    Triggers the entitlements sign-in form.

    Show the Entitlements register form

    tp-entitlements-register://
    
    Click to copy

    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>
    
    Click to copy

    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://
    Click to copy

    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]
    Click to copy

    Allows you to trigger a phone call.

    Example:

    callto:+32493252577
    
    tel:+32493252577
    Click to copy

    12. Sharing on social media

    To trigger the sharing sheet, you use the following url-scheme:

    tp-share://
    Click to copy

    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://
    Click to copy

    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://...)

    14. Going back in Navigation History

    This special url scheme can be used in all the same places as tp-collection links and goes back in the navigation stack for a specific number of steps. The syntax is as follows:

    tp-navigate-up://[number-of-steps]
    Click to copy

    The number-of-steps indicates how many steps you want to go back.

    Example:

    Application XYZ has the following structure:

    • Root Collection (browse mode)
      • Languages Collection (browse mode)
        • English Collection (browse mode)
          • English Document 1 (detail mode)

    Some specific uses and what the result will be (in this case):

    • English document 1: tp-navigate-up://1 takes you to the English Collection.
    • English document 1: tp-navigate-up://2 takes you to the Languages Collection.
    • English document 1: tp-navigate-up://3 takes you to the Root Collection.
    • English document 1: tp-navigate-up://200 also takes you to the Root Collection.

    IMPORTANT NOTE:

    tp-navigate-up:// is supported only on iOS and Android. It cannot be used in the browser client.

    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>
    Click to copy

    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=1
    Click to copy

    Although 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.pdf
    Click to copy

    While 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=1
    Click to copy

    When 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=1
    Click to copy

    To 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=1
    Click to copy

    19. Open in embedded web browser

    tp-open-in-web-browser=1
    Click to copy

    Adding 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://";
    Click to copy

    will execute the following JavaScript function:

    function twixlOnGetDeviceInfo(deviceUDID, appVersion, appIdentifier, entitlementToken) {
    }
    Click to copy

    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) {
    }
    Click to copy

    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://
    Click to copy
    tp-get-custom-vars://
    Click to copy

    Example:

    tp-set-custom-vars://?name=&product=
    Click to copy

    MORE INFO ABOUT CUSTOM VARS:

    Custom Variables rely on Advanced Scripting. For more info about Advanced Scripting and an example, see:

    Was this article helpful?

    2 out of 4 found this helpful