Skip to content

Deep Linking#

The Storyteller SDK makes it possible to handle the deep links. The implementing app should follow the official Android guideline.

Showcase examples#

In order to enable it separate intent filters need to be added to the implementing app's AndroidManifest.xml.

    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data
            android:scheme="https"
            android:host="[tenant_name].ope.nstori.es"
            android:pathPattern="/open/.*/.*" />

    </intent-filter>

    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data
            android:scheme="https"
            android:host="[tenant_name].shar.estori.es"
            android:pathPattern="/go/.*/.*" />
    </intent-filter>

    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data
            android:pathPattern="/.*/.*"
            android:scheme="[tenant_name]stories"
            android:host="open"/>
    </intent-filter>

In the above, [tenant_name] is the lower case variant of your tenant's name. For example, if the tenant name is "MyTenant", then [tenant_name] should be "mytenant". Each link should be added as a separate intent-filter as in the example above. If Android system starting from Android 11 will fail to auto-verify any of the links which should be auto-verified it will disable the verification for all of them. This will result in the app not being able to handle any of the deep links in the Manifest.

Note: Please note that the last intent filter above for "[tenant_name]stories" does not have android:autoVerify="true" attribute. This is because the auto-verification is not supported for custom non https schemes.

The deep link can be handled by using Storyteller.openDeepLink, which opens the link. This can be done automatically by using openDeepLink or manually using Story or Page ID (openStory and openPage respectively).

Example 1:

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.main)

  val data: Uri = intent?.data ?: return
  val url = data.toString()

  if (Storyteller.isStorytellerDeepLink(url)) {
    Storyteller.openDeepLink(this, url) { error ->
      // Handle error (content not found, invalid deep link, etc.)
    }
  }
}

Note: Starting from Android 6.0+, a Digital Asset Links file is required to properly handle https deep links. It can be generated inside the Storyteller CMS and it requires you to add your app's package name and SHA-256 fingerprint of certificate the app was signed with. For more information on the Digital Asset Links file, see the Android developer documentation

To generate the Digital Asset Links file in the Storyteller CMS:

  1. Navigate to the 'Apps' section on the left-hand side
  2. Click on the 'New App' button

  3. Fill out the 'Package Name' and 'SHA 256 Cert Fingerprint'

  4. Package Name - this is the application ID declared in the app's build.gradle file. This value should be the same as the "App Store Identifier" entered above. E.g. com.example.myapp.

  5. SHA 256 Cert Fingerprint - this is the SHA256 fingerprint of your app's signing certificate. You can use the following command to generate the fingerprint via the Java keytool: keytool -list -v -keystore my-release-key.keystore. Or, if using the Google Play Store Signing, the SHA256 signature can be downloaded using the Google Play Console:
  6. Login to the Play Console
  7. Select the app you want to configure
  8. Go to Setup → App integrity
  9. Copy the SHA-256 value under "App signing certificate"
  10. This value should be entered into your Storyteller App's form without the "SHA-256: " prefix. E.g.15:8D:E9:83:C5:73...

CMS App page

After saving your app, the Digital Asset Links file for your tenant can be viewed at the following URLs: https://yourtenantname.ope.nstori.es/assetlinks.json and https://yourtenantname.ope.nstori.es/.well-known/assetlinks.json

Note: the file may take up to 5 minutes to appear after saving your App.

The openDeepLink function in the Storyteller SDK handles different types of deep links.

fun openDeepLink(activity: Activity, url: String, onError: (StorytellerError) -> Unit = {})

This call makes Storyteller open the provided deep link (showing the requested content). Use Storyteller.isStorytellerDeepLink(url) to check whether a URL is a Storyteller deep link before calling this method.

Parameters:

  • activity - Activity.

  • url - this is the Deep Link URL.

  • onError - called for invalid links, replacement lifecycle/timeout failures, or unavailable Story, Page, Category, Clip Collection, or Clip content. A Sheet fetch failure uses the existing inline Sheet error UI.

Replacing an active player#

When openDeepLink receives a valid Storyteller link while a Story or Clip player is active, the SDK dismisses the active Storyteller presentation before opening the requested content. The replacement dismissal is not animated.

If several valid links arrive while the active presentation is being dismissed, only the latest link opens. Superseded requests are abandoned and do not receive a separate onError callback. Invalid or structurally incomplete links are rejected through onError without dismissing the active player.

Replacement uses one dismissal transaction for Story, Page, Category, Clip Collection, Clip, and Sheet routes. The previous presentation's normal dismissal analytics and onPlayerDismissed() host callback complete once before the requested route starts opening. Sheet routes do not issue a second standalone dismissal.

The supplied Activity must remain available until dismissal finishes. If the Activity finishes or player dismissal cannot be confirmed within the bounded wait, onError is called and the requested content does not open.

Content availability is checked after the previous presentation has been dismissed:

  • An unavailable Story, Page, Category, Clip Collection, or Clip reports onError; no replacement player opens.
  • An unavailable Sheet preserves the existing Sheet behavior by showing its inline error and retry UI. It does not call onError for this post-open fetch failure.

For SDK versions before 11.7.0, clients can apply this temporary workaround. Keep the dismissal unconditional because a backgrounded player may not be reflected by Storyteller.isPlayerVisible.

Storyteller.dismissPlayer(animated = false) {
  Storyteller.openDeepLink(this, url, ::handleError)
}

Story Category#

  • For story category deep links, the openDeepLink method identifies and processes links based on the following structure:
  • The link contains either /open/category/ or /go/category/
  • The link includes a category identifier following the /category/ part of the path
  • The category ID is extracted from the deep link and the openCategory function is called with the extracted category ID
  • eg: "https://[tenantname].shar.estori.es/go/category/123456" or "https://[tenantname].shar.estori.es/open/category/123456"

Clip collection#

  • For clip collection deep links, the openDeepLink method identifies and processes links based on the following structure:
  • A collection-only link contains /open/clips or /go/clips and does not require a Clip ID in the path
  • A link targeting a specific Clip contains /open/clip/((clipId)) or /go/clip/((clipId))
  • The link must include a collectionId query parameter
  • An optional categoryId query parameter can be included to specify a category to open in the Clip Collection as an initial category (initialCategory of the openCollection method)
  • The information extracted will be used to call openCollection()
  • Collection eg: "https://[tenantname].shar.estori.es/go/clips?collectionId=abcd1234"
  • Clip eg: "https://[tenantname].shar.estori.es/open/clip/((clipId))?collectionId=abcd1234&categoryId=123456"

Story Deep link#

  • For story deep links, the openDeepLink method identifies and processes links based on the following structure:
  • The link is confirmed to be a URI object
  • It extracts storyId or pageId from the deep link via segment positions. One must be present
  • It proceeds to call openPage() or openStory() with either the storyId or pageId,
  • eg openStory: https://[tenantname].shar.estori.es/go/story/((storyId)) or openPage: https://[tenantname].shar.estori.es/go/page/((pageId))

Sheet#

  • For sheet deep link, the openDeepLink method identifies and processes links based on the following structure:
  • The link contains either /open/sheet/ or /go/sheet/
  • It extracts sheetId from the deep link via segment positions. One must be present
  • eg: "https://[tenantname].shar.estori.es/go/sheet/123456" or "https://[tenantname].ope.nstori.es/open/sheet/123456"

It is generally recommended to author your own deep link and extract the required data. This is to not upset the current state and deep link integration of your app and to allow for more control over the deep link handling then use openStory()/openPage()/openCollection()/openCategory()/openSheet() to pass the relevant data to the SDK, see the Open Player (or AdditionalMethods) documentation for more information.

isStorytellerDeepLink(String) checks if the string is a valid Storyteller deep link.

Storyteller.isStorytellerDeepLink("stories://open/9329bed2-2311-69b8-cbcf-39fcf8d8af21/f6445df7-bd79-71de-cdfb-39fd071568a1")