We’re here to help

Custom URL Schemes for article-based apps

Follow

A number of custom URL schemes can be used from within your article content, to link to a particular collection or article.

URL schemes for collections

From within your article content, you can use special URL schemes to link to a collection or article.

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]?mode=browse
Will open the collection in browse mode.
tp-collection://[collection-name]?mode=detail
Will open the collection in detail mode.
tp-collection://[collection-name]/[article-name]
Will link to a specific article in a different collection.
tp-collection://parent
Will link to the parent collection of your current article.
tp-collection://root
Will link to the root collection of your app.

Article and page links

If you want to add a link to a particular article within a collection, you can do so by using the URL scheme below:

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 as follows:

tp-pagelink://[article_name]/[page_number]

A number of other URL schemes for relative article and page navigation are also available:

tp-next-article://show
Go to the next article.
tp-previous-article://show
Go to the previous article.
tp-first-article://show
Go to the first article of the publication.
tp-last-article://show
Go to the last article of the publication.
tp-next-page://show
Go to the next page (if at the last page of an article, go to the next page in the following article).
tp-previous-page://show
Go to the previous page (if at the first page of an article, go to the last page of the previous article).
tp-first-page://show
Go to the first page of an article.
tp-last-page://show
Go to the last page of an article.
tp-article-top://show
Go to the top of a long-page article.
tp-article-bottom://show
Go to the end of a long-page article.

Going back in Navigation History (introduced in version 5.5)

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.

Paywall

tp-paywall://show

in an article-based app, there is no separate subscriptions dialog, as everything is part of the paywall which is shown as a layer top of a collection. You can manually trigger the paywall by using this special URL.

Entitlements

Show the Entitlements sign-in form

tp-entitlements-signin://self

Triggers the entitlements sign-in form.

Show the Entitlements register form

(Available in the kiosk info cell - infoCell.html)

tp-entitlements-register://self

Triggers the entitlements register form. This only works if the entitlements server provides a "register" action.

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

(Available in the kiosk info cell - infoCell.html)

tp-entitlements-clear-token://self

Clears the entitlements token (can be used for testing purposes).

Phone call

callto:[number]

Allows you to trigger a phone call. Note that this will work on phones only.

Example:

callto:+32493252577

Searching (available since version 5.5)

To trigger the search-dialog in article-based applications, you use the following url-schemes:

tp-search://

Shows an empty search-dialog

tp-search://[keyword]

Executes a search-command with the specified keyword.

Example (search for content with the word twixl):

tp-search://twixl

Launching an app

It is possible to trigger launching an app from within a Twixl publication 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.

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.

Opening a hyperlink in the device browser

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 an extra parameter to your URL:

tp-open-in-device-browser=1

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

Open in embedded web browser

tp-open-in-web-browser=1

Adding this url parameter to a hyperlink in an infoCell will open the link in the embedded web browser instead of opening within the infoCell itself.

Was this article helpful?
1 out of 1 found this helpful