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.

    You can use the following scheme:

    tp-collection://[target_collection_name]/[target_article_name]

    The syntax is as follows:

    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 (currently 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.

    tp-pagelink://[article_name]

    If you want to add a link to a particular page in an article 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

    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. Searching

    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
    • 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).

    7. Paywall & subscriptions

    tp-paywall://

    You can manually trigger the paywall by using this special URL.

    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.

    8. 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).

    9. 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.

    10. Making a phone call

    callto:[number] or tel:[number]

    Allows you to trigger a phone call.

    Example:

    callto:+32493252577
    
    tel:+32493252577

    11. Sharing on social media

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

    tp-share://

    12. 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]

    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.

    13. 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 the URL to launch the app would be: comtwixlmediamyapp://

    IMPORTANT NOTE:

    This will only work if the app is already installed on the device.

    14. 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>

    This is now supported anywhere in an article-based / issue-based / single-issue app where you can enter an URL.

    IMPORTANT NOTE:

    This will only work if the app has already been installed on the device.

    15. Opening a hyperlink in the device browser

    tp-open-in-device-browser=1

    Although in most cases, you want to keep readers in the embedded browser, sometimes you may want to open a link directly in Safari on iPad or in the default browser on Android. 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.

    Some examples:

    The URLs below will open in the embedded app browser:

    http://www.website.com/file.pdf?id=1
    http://www.website.com/file2.pdf

    And these will open in the device browser:

    http://www.website.com/file.pdf?id=1&tp-open-in-device-browser=1
    http://www.website.com/file2.pdf?tp-open-in-device-browser=1

    16. Open in embedded web browser

    tp-open-in-web-browser=1

    Adding this url parameter to a hyperlink will open the link in the embedded web browser instead of opening inline.

    17. 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.

    18. 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:

    Was this article helpful?

    2 out of 4 found this helpful