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 static method 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
  if (data != null && Storyteller.isStorytellerDeepLink(data.toString()) {
      //open link automatically
      Storyteller.openDeepLink(this, data.toString())
    }
}

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. There are 3 different ways in which it does this

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

This call makes Storyteller open the provided deeplink (showing the requested Page/Story). The method returns true if the URL is a Storyteller deeplink

Parameters:

  • activity - Activity.

  • url - this is the Deep Link URL.

  • onError - this is called when there is any issue with opening the deep link (e.g. the requested content is no longer available)

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:
  • The link contains either /open/clip, /go/clip, /open/clips, or /go/clips
  • The link includes a unique identifier (UUID) in the path
  • 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()
  • 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 deeplink and extract the required data. This is to not upset the current state and deeplink integration of your app and to allow for more control over the deeplink 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")