Implementing Storyteller Delegate Callbacks#

Table of Contents#

StorytellerDelegate
StorytellerListViewDelegate

A StorytellerDelegate has methods for managing Storyteller events. It is used as global object for handling all events when opening a Story Player with and without the StorytellerStoriesRowView or StorytellerStoriesGridView. Please see the dedicated StorytellerListViewDelegate below for handling events related to rows and grids.

Showcase examples#

StorytellerDelegate#

To use global StorytellerDelegate, implement the StorytellerDelegate interface by overriding the required methods and set it in Storyteller object.

Example:

    Storyteller.storytellerDelegate = myCustomStorytellerDelegate

onUserActivityOccured#

The onUserActivityOccurred(type: StorytellerUserActivity.EventType, data: UserActivityData) method is is called when an analytics event is triggered. See the dedicated Analytics page for more information on analytic events.

getAd#

The getAd(adRequestInfo: StorytellerAdRequestInfo, onComplete: (StorytellerAd) -> Unit = {}, onError: () -> Unit) method is called when the tenant is configured to request ads from the containing app and the SDK requires ad data from the containing app. For more information on how to supply ads to the Storyteller SDK, see the dedicated Ads page.

userNavigatedToApp#

The userNavigatedToApp(url: String) method is called when a user taps on an action button on a Page which should direct the user to a specific place within the integrating app. More information on In App links Navigating to App. For more information on deep linking, see the dedicated Deep Linking page.

onShareButtonTapped#

The onShareButtonTapped(text: String, title: String, url: String) method is called when Storyteller.useCustomShareHandling = true and the user taps a Story or Clip share entry point.

When custom share handling is enabled:

The SDK does not open the Android system share sheet internally.
The SDK calls onShareButtonTapped instead.
Existing share-tap analytics continue to be emitted by the SDK.
Share success/completion remains the responsibility of the integrating app.

Payload details:

text - the SDK-generated share text for the selected Story or Clip
title - the Story or Clip title used for display in the host app
url - the deeplink URL for the selected Story or Clip

Example:

Storyteller.useCustomShareHandling = true

override fun onShareButtonTapped(
  text: String,
  title: String,
  url: String,
) {
  openCustomShareSheet(
    title = title,
    text = text,
    url = url,
  )
}

Analytics#

The callback onUserActivityOccurred provides analytics events and corresponding data triggered internally by the SDK. This information can be used in your app.

The following parameters are passed to the callback method:

type - type of event that occurred, as a StorytellerUserActivity.EventType enum
data - an object containing data about the event which occurred

Example:

    ...
    override fun onUserActivityOccurred(type: StorytellerUserActivity.EventType, data: UserActivityData) {
        if (type == StorytellerUserActivity.EventType.OPENED_STORY) {
            // Retrieve the story id value
            val openStoryId = data.storyId
            // Retrieve the story title value
            val openStoryTitle = data.storyTitle

            // Report retrieved values from your app
        }
    }

For a detailed discussion of all the relevant events and properties please see the dedicated Analytics page.

Client Ads#

By implementing getAd, you can provide custom ad data for the SDK to render, this is only applicable when the ad configuration is set to Integrating App in the CMS. Ad data can be obtained asynchronously, and should be provided using the onComplete closure parameter.

Example:

    ...
    override fun getAd(adRequestInfo: StorytellerAdRequestInfo, onComplete: (StorytellerAd) -> Unit = {}, onError: () -> Unit) {
        // Action to get some ads
        val ad = getMyAd()
        // Convert the ad to a StorytellerAd
        val storytellerAd = convertToStorytellrAd(ad)
        // Provide the ad to the SDK
        onComplete(ad)
    }

For a detailed discussion of all the relevant considerations, please see the dedicated Ads page.

configureWebView#

This method allows you to configure the WebView with custom settings or actions when the Storyteller SDK, is to display a WebView.

It takes three parameters: the WebView to configure, an optional URL string, and an optional favicon Bitmap. This method is called from the onPageStarted method of a custom WebViewClient when a new page starts loading in the WebView.

Parameters#

view: WebView - The WebView instance to be configured.
url: String? - (Optional) The URL string associated with the WebView page that is being loaded.
favicon: Bitmap? - (Optional) The favicon Bitmap to be displayed for the WebView page.

Example Usage#

To intercept and customize WebViews created by the Storyteller SDK, you can implement your own version of the configureWebView method.

Here is an example of how to do this:

override fun configureWebView(
  view: WebView,
  url: String?,
  favicon: Bitmap?
) {
  // Your custom configuration code goes here
  // The following line shows a simple alert in the WebView with the message "test webview javascript".
  view.evaluateJavascript("javascript: alert('test webview javascript');", null)
}

Followable Categories#

The method fun categoryFollowActionTaken(category: Category, isFollowing: Boolean) is invoked when a user adds or removes a category from within SDK's UI.

The callback method receives the following parameters:

category - An object representing the clip category
isFollowing - A boolean value indicating whether the user is following or unfollowing the specified category

customScreenForCategory#

The fun customScreenForCategory(): @Composable (StorytellerFollowableCategoryCustomScreen) -> Unit method is called when a user navigates to a followable category screen. The callback receives a StorytellerFollowableCategoryCustomScreen object. with the following parameters:

pendingModifier - a Modifier object that is used to apply custom styling to the screen, this must be applied to the root composable of your custom screen
category - a Category object that is the category that the user is navigating to
onBackClicked - a () -> Unit a callback that should be called when the user clicks the back button from the custom screen, this is to let Storyteller know that the user has navigated back to the previous screen. If this is not called, the user will be stuck on the custom screen and unable to navigate back to the previous screen.

Example:

  override fun customScreenForCategory(): @Composable()
  ((StorytellerFollowableCategoryCustomScreen) -> Unit) {
    return { (pendingModifier, category, onBackClicked) ->
      Scaffold(
        modifier = pendingModifier,
        topBar = {
          CenterAlignedTopAppBar(
            title = {
              Text("${category.displayTitle}")
            },
            navigationIcon = {
              IconButton(onClick = onBackClicked) {
                Icon(
                  imageVector = Icons.AutoMirrored.Default.ArrowBack,
                  contentDescription = "Back"
                )
              }
            }
          )
        }
      ) { paddingValues ->
        Surface(
          modifier = Modifier.padding(paddingValues)
        ) {
          Box(
            modifier = Modifier.fillMaxSize(), contentAlignment = androidx.compose.ui.Alignment.Center
          ) {
            Text("Custom layout for ${category.displayTitle}")
          }
        }
      }
    }
  }

Alongside the customScreenForCategory callback, the Storyteller object also has a useCustomScreenForCategory property that is a (Category) -> Boolean callback. This is to allow the developer to conditionally show the custom screen for a specific category or default to the original implementation of Followable Categories by Storyteller.

The callback must return a Boolean value, which determines whether the custom screen should be shown for the given category.

Example:

    Storyteller.useCustomScreenForCategory = {
      if (it.type == "custom") {
        // return true if you want to show the custom followable category screen
        true
      } else {
        // return false if you want to show the default followable category screen
        false
      }
    }

The customScreenForCategory will only be called if the useCustomScreenForCategory callback returns true for the given category. Otherwise, if it's not set or returns false, the default implementation of the Followable Categories by Storyteller will be used.

Similarly, Storyteller.useCustomShareHandling = true enables host-managed share handling through onShareButtonTapped. If it remains false, the SDK keeps the default Android share sheet behavior.

bottomSheetScreen#

The fun bottomSheetScreen(urlProvider: () -> String, onDismiss: () -> Unit): @Composable () -> Unit method is called when the deep link includes the query parameter shouldUseModal=true.

urlProvider A callback that provides the URL to be loaded in the WebView or used for other purposes.
onDismiss A callback invoked when the user dismisses the bottom sheet.

Example:

    override fun bottomSheetScreen(
      urlProvider: () -> String,
      onDismiss: () -> Unit
    ): @Composable (() -> Unit) {
      return {
        DemoBottomSheet(urlProvider, onDismiss)
      }
    }

StorytellerListViewDelegate#

A StorytellerListViewDelegate has methods for managing StorytellerStoriesRowView and StorytellerStoriesGridView events.

How to Use#

To use StorytellerListViewDelegate, implement the StorytellerListViewDelegate interface and override the required methods:

onDataLoadStarted#

The onDataLoadStarted() method is called when the network request to load data for all Stories has started.

onDataLoadComplete#

The onDataLoadComplete(success: Boolean, error: Error?, dataCount: Int) method is called when the data loading network request is complete.

Property	Description
`success`	This confirms whether or not the request was successful
`error`	The HTTP error if the request was not successful
`dataCount`	The number of Stories loaded

onTileTapped#

The onTileTapped(tileType: StorytellerTileType) method is called when a user taps on a tile inside a row or grid. This callback is executed before the player Activity is opened.

tileType is a sealed class describing the tapped Story or Clip. Common SDK callback fields are id, nullable title, nullable 1-based tileIndex, and nullable custom metadata. Story adds categories; Clip adds collectionId and categories.

Example:

override fun onTileTapped(tileType: StorytellerTileType) {
    val title = tileType.title
    val oneBasedIndex = tileType.tileIndex
    val publisher = tileType.metadata?.get("publisher")

    when (tileType) {
        is StorytellerTileType.Story -> {
            // Handle story tile tap
            val storyId = tileType.id
            val categories = tileType.categories
        }
        is StorytellerTileType.Clip -> {
            // Handle clip tile tap
            val clipId = tileType.id
            val collectionId = tileType.collectionId
            val categories = tileType.categories
        }
    }
}

The SDK snapshots custom metadata from the originating content. metadata is null when the source omitted it or refreshed content can no longer be resolved, and empty when the source supplied no entries. title or tileIndex can also be null if the tapped item is removed during a refresh; a resolved title can be an empty string when the source supplies no title text. Application-created or data-class-copied StorytellerTileType values have no SDK callback context and return null for all three fields. The generated subtype equals, hashCode, and toString functions retain their legacy constructor-only behavior and do not include callback context.

Note: When theme.lists.enablePlayerOpen is set to false, this callback becomes the primary way to handle tile interactions, as the SDK will not automatically open the player.

onPlayerDismissed#

The onPlayerDismissed() method is called when user closes Storyteller Player.

Example:

    val StorytellerStoriesRowView = StorytellerStoriesRowView()
    StorytellerStoriesRowView.delegate = myDelegate

Error Handling#

By using the callback function onDataLoadComplete and the data it provides, you can handle the current state of the StorytellerStoriesRowView appropriately in your app.

Note: dataCount is the total number of Stories in the existing StorytellerStoriesRowView at any given time

Example:

    ...
    override fun onDataLoadComplete(success: Boolean, error: StorytellerError?, dataCount: Int) {
        if (success) {
            // stories data has been loaded successfully
            // dataCount is the current total number of stories, including newly added/removed data
        } else if (error != null) {
            // an error has occurred, unwrap the error value for more information
            // dataCount is the total number of stories before loading began
        }
    }

Another example:

    ...
    override fun onDataLoadComplete(success: Boolean, error: StorytellerError?, dataCount: Int) {
        if (error != null && dataCount == 0) {
            // stories have failed to load with error and there is no data to show
            // you may wish to hide the `StorytellerStoriesRowView` instance here
            StorytellerStoriesRowView.visibility = View.GONE
        }
    }