Skip to content

StorytellerModule#

The StorytellerModule module is a interface you can adopt to handle the fetching of ads and recording of user activity events from Storyteller. It contains the following methods:

Showcase examples#

Methods#

    abstract fun onUserActivityOccurred(type: StorytellerUserActivity.EventType, data: UserActivityData)

    abstract fun getAd(
        adContext: AdContext,
        adRequestInfo: StorytellerAdRequestInfo,
        onComplete: (StorytellerAd) -> Unit,
        onError: (String) -> Unit
    )

    fun getBottomBannerAd(
        adContext: AdContext,
        adRequestInfo: StorytellerAdRequestInfo,
        onComplete: (StorytellerAd) -> Unit,
        onError: (String) -> Unit
    )

Analytics#

The callback onUserActivityOccurred provides analytics events and corresponding data to be 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) {
        when (type) {
            StorytellerUserActivity.EventType.AD_ACTION_BUTTON_TAPPED -> onAdAction(data)
            StorytellerUserActivity.EventType.OPENED_AD -> onAdStart(data)
            StorytellerUserActivity.EventType.FINISHED_AD -> onAdEnd(data)
            else -> Log.d("StorytellerModule", "Unhandled event type: $type")
        }
    }

See the Analytics page for more information.

Ads#

By implementing getAd and getBottomBannerAd, 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 returned via the appropriate callback.

getAd#

The getAd method is called when the SDK needs a fullscreen ad. The onComplete callback should be called when the ad data is ready, and the onError callback should be called if an error occurs.

    override fun getAd(
        adContext: AdContext,
        adRequestInfo: StorytellerAdRequestInfo,
        onComplete: (StorytellerAd) -> Unit,
        onError: (String) -> Unit
    ) {
        val ad = fetchAd(adContext, adRequestInfo)
        if (ad != null) {
            onComplete(ad)
        } else {
            onError("Failed to fetch ad")
        }
    }

getBottomBannerAd#

The getBottomBannerAd method is called when the SDK needs a bottom banner ad (displayed at the bottom of clips). The adContext.isBottomBanner property will be true for these requests. Only 300x50 and 320x50 ad sizes are supported.

    override fun getBottomBannerAd(
        adContext: AdContext,
        adRequestInfo: StorytellerAdRequestInfo,
        onComplete: (StorytellerAd) -> Unit,
        onError: (String) -> Unit
    ) {
        val bannerAd = fetchBottomBannerAd(adContext, adRequestInfo)
        if (bannerAd != null) {
            onComplete(bannerAd)
        } else {
            onError("Failed to fetch bottom banner ad")
        }
    }

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

Technical Consideration#

Use of a custom StorytellerModule is optional. If you do not implement this interface, the SDK will use the default implementation see Ads. It must be provided to the SDK when initializing the Storyteller SDK using the Storyteller.modules method to see Gam Ads.