Skip to main content
Version: 3.x.x

Configuration

You can configure the StorifyMe SDK to suit your specific needs by customizing various options and settings.

Custom Gateway Request Headers​

If your custom gateway requires an app-owned session header, register the request interceptor before initializing the SDK. It runs synchronously for each stories, base-template, audience, and ads content API request routed through customBaseUrl, so the app can provide a refreshed token on every request. The callback receives the absolute request URL and current headers, including accountId; return the complete header map to send.

StorifyMeSDK.setRequestInterceptor { url, headers ->
    headers + ("Authorization" to "Bearer ${session.currentToken()}")
}

StorifyMeSDK.init(
    context = this,
    apiKey = "YOUR_API_KEY",
    accountId = "YOUR_ACCOUNT_ID",
    customBaseUrl = "https://gateway.example.com",
)

The interceptor only applies to content API requests using the configured custom base URL. It does not add headers to media or WebView traffic. The SDK does not store or log returned header values. If the callback throws, the request fails. Keep it synchronous and make sure the gateway does not redirect requests to a different origin; the SDK does not reapply headers after redirects.

Pass null to StorifyMeSDK.setRequestInterceptor to unregister the callback.

Configuration​

Get widget properties​

Retrieve story thumbnail size and other UI properties by calling this method.

main.kt
storiesView.getWidgetProperties()

Configure Stories playback​

Playback of stories can be customized.

Deprecated enum names

StoryPlaybackBehaviour and its values are deprecated in 3.0.0. The legacy widget setter below remains available for existing integrations. For new programmatic opens, pass StorifyMeExperiencePlaybackBehaviour in a StorifyMeExperienceBehaviour to openWidgetExperienceBy... or StorifyMeSDK.openExperienceByHandle(...).

The default behavior is for stories to continue where the user left off, anytime in the past. This can be easily adjusted by setting the StoryPlaybackBehaviour behavior.

  • RESTART_STORIES_ON_APP_LAUNCH - On every app launch, all stories will start from beginning
  • RESTART_STORIES_WHEN_OPEN - On every stories preview launch, all stories will start from beginning
  • ALWAYS_RESUME_STORY_WHERE_STOPPED - Stories will resume where user previously stopped watching them, no matter if app was earlier terminated or stories closed
main.kt
storiesView.setPlaybackOptions(StoryPlaybackBehaviour.RESTART_STORIES_ON_APP_LAUNCH)

Configure Audio control​

Audio control of stories can be customized.

Deprecated enum names

StoryAudioBehaviour and StoryAudioState are deprecated in 3.0.0. The legacy widget setter below remains available for existing integrations. For new programmatic opens, use StorifyMeExperienceAudioBehaviour and StorifyMeExperienceAudioState in StorifyMeExperienceBehaviour.

It can be easily adjusted by setting StoryAudioBehaviour.

  • APPLY_CHANGE_FOR_PRESENTED_STORIES (default since 2.8.0) - When a user mutes/unmutes a story, that change applies to all stories currently presented in the widget. After dismissing and reopening stories, the default audio state is restored. This matches iOS behavior.
  • APPLY_LAST_USER_CHANGE_FOR_ALL_FUTURE_STORIES - Default state of audio will be used every time, until user changes manually state of audio. After that last user change will be applied to every story shown.
  • APPLY_CHANGE_FOR_SINGLE_STORY - The same behaviour will be applied on every story launch, no matter what user done in past. When user mutes/unmutes one story, that change will be applied for that story only.
main.kt
storiesView.setAudioOptions(
    StoryAudioBehaviour.APPLY_LAST_USER_CHANGE_FOR_ALL_FUTURE_STORIES,
    defaultState = StoryAudioState.MUTED)

Configure Widget Posters​

The widget supports both GIF posters and video posters. Each type has a different default state, and you can control them in code depending on your requirements. If both are disabled, the widget will display a static image by default.

GIF Posters​
  • Default: Enabled (automatically play in the widget)
  • Usage: You can disable or enable them programmatically
main.kt
// Disable GIF posters
storiesView.setGifPosterEnabled(false)

// Enable GIF posters
storiesView.setGifPosterEnabled(true)
Video Posters​
  • Default: Disabled (do not play automatically)
  • Usage: You can enable or disable them programmatically
main.kt
// Enable video posters
storiesView.setVideoPosterEnabled(true)

// Disable video posters
storiesView.setVideoPosterEnabled(false)

Both poster types can be enabled or disabled depending on your use case. For example, you might enable them to provide richer previews and a more engaging user experience, or disable them to reduce data usage and improve performance on lower-end devices.

Configure Full Screen Display​

The SDK provides control over how stories and shorts are displayed on the screen. You can configure each widget to display content either in full screen mode or in a safe area that respects system UI elements like the status bar and camera cutouts.

Display Modes​
  • Safe Area (Default): Content is displayed within the safe area, respecting system UI elements such as the status bar and camera cutouts. This ensures that important content is not obscured by device hardware or system overlays.
  • Full Screen: Content extends to cover the entire screen, including areas behind the status bar and camera cutouts.
tip

This feature is particularly useful for shorts, where full screen immersion can enhance the viewing experience. For stories, the default safe area mode typically provides better usability.

Default Behavior​

By default, both stories and shorts are displayed in safe area mode (not full screen). This ensures content is always visible and not hidden behind device notches or system UI elements.

Usage​

You can enable or disable full screen mode for each widget individually:

main.kt
// Enable full screen mode
storiesView.setFullscreenEnabled(true)

// Disable full screen mode (default behavior)
storiesView.setFullscreenEnabled(false)

When full screen is disabled, the content will be displayed in the safe area, ensuring optimal visibility across all device types and screen configurations.

Configure URL Presentation Control​

The StorifyMeURLPresentationBehaviour provides flexible options for controlling the presentation of URLs within the application. By configuring this setting, you can define how URLs are displayed when presenting stories.

Options

  • IN_APP_BROWSER: URLs are presented within an in-app browser. User interactions with URLs are maintained across successive story presentations, ensuring consistent behavior.
  • EXTERNAL_BROWSER (Default): URLs consistently open in an external browser application. User interactions with URLs remain isolated to individual story presentations and do not affect other content.

The default behavior is to open URLs in an external browser. To set a different default behavior, adjust the StorifyMeURLPresentationBehaviour accordingly.

Example usage:

main.kt
storiesView.setURLPresentationBehaviour(
  StorifyMeURLPresentationBehaviour.IN_APP_BROWSER)

This allows you to tailor the URL presentation experience to match your users' preferences and ensure a seamless browsing experience.

Configure Widget Scroll Navigation Options​

The StorifyMeWidgetScrollNavigationOptions provides options for controlling where to place navigation icons.

Example usage:

main.kt
storiesView.setWidgetScrollNavigationOptions(StorifyMeWidgetScrollNavigationBehaviour.VERTICAL_CENTERED_CONTROLS)

Configure Direction for Widget​

The desired direction for the StorifyMe widget can be configured using the setDirection method.

Enum: StorifyMeContentDirection

  • ltr: Displays from left to right.
  • rtl: Displays from right to left.
main.kt
val storiesView = findViewById<StorifyMeWidget>(R.id.storiesView)
val config = StorifyMeWidgetConfig.Builder().apply {
  // Set direction to Right-to-Left (RTL)
  setDirection(StorifyMeContentDirection.RTL)
}.build()

storiesView.config = config
storiesView.widgetId = WIDGET_ID
storiesView.load()
Deprecated

Prior to 3.0.0 the type was StoriesView. Use StorifyMeWidget in all new and migrated code.

Configure Language for Widget​

Widget content defaults to the device language. To request a specific language, use setLanguage with a language code:

main.kt
val storiesView = findViewById<StorifyMeWidget>(R.id.storiesView)
val config = StorifyMeWidgetConfig.Builder().apply {
  // Set the language to English
  setLanguage("en")
}.build()

storiesView.config = config
storiesView.widgetId = WIDGET_ID
storiesView.load()

Updating a widget's configuration after it has loaded refreshes its content from page one.

Configure Widget Theme​

By default, the widget follows the host app's system theme. To override it for one widget, set LIGHT or DARK in its configuration. The effective theme is sent with the content request and is part of the cache identity.

main.kt
val config = StorifyMeWidgetConfig.Builder()
    .setTheme(StorifyMeWidgetTheme.DARK)
    .build()

storiesView.config = config
storiesView.load()

Configure Experience Viewer Orientation​

Set the global orientation policy before opening a viewer. This applies to widget-opened experiences, handle previews, and the SDK in-app browser.

main.kt
StorifyMeSDK.instance.experienceViewerOrientation =
    StorifyMeExperienceViewerOrientation.PORTRAIT_AND_LANDSCAPE

Use PORTRAIT_ONLY to keep the viewer in portrait. Android or the host app's manifest may restrict orientation requests on some large-screen devices.

Filter by Experience ID​

To request only selected experiences in a widget, pass their numeric IDs through the config builder:

main.kt
val config = StorifyMeWidgetConfig.Builder()
    .setExperienceIds(listOf(101L, 202L))
    .build()

storiesView.config = config
storiesView.load()

Pass null or an empty list to clear the filter.

Set the Customer ID​

Set the customer ID globally after sign-in or whenever the active user changes:

main.kt
StorifyMeSDK.instance.configureCustomerId("customer-123")

StorifyMeWidgetConfig.Builder.setCustomerId(...) is deprecated. The global SDK setting also updates the SDK's customer-scoped storage and cache behavior.

Disable the initial onboarding tutorial​

Call this during app setup if you do not want the SDK to show its first-time interaction tutorial:

main.kt
StorifyMeSDK.instance.disableInitialOnboarding()

Methods​

Show StorifyMe Notification​

This feature enables the display of notifications while presenting stories, enhancing user engagement and interaction within the platform. Users can now receive notifications that provide additional context or updates related to the ongoing story, enhancing the overall storytelling experience.

To implement this feature, use the following code:

main.kt
StorifyMeSDK.instance.showNotification(
  "Notification title example",
  "Message example",
  duration = 3.0)

Replace the parameters with the desired title, message and duration for the notification display.

Pause and Resume Playback​

This feature allows you to pause and resume the playback of stories and reels with the StorifyMe playback controller. You can control the visibility of playback controls during this process.

To Pause Playback:

main.kt
StorifyMeSDK.instance.playbackController.pausePlayback(StorifyMeControlsVisibility.VISIBLE)

Use this method to pause the current story or reel with the option to keep playback controls visible.

To Resume Playback:

main.kt
StorifyMeSDK.instance.playbackController.resumePlayback(StorifyMePlaybackMode.FROM_BEGINNING)

Use this method to resume the paused story or reel, specifying whether playback should start from the beginning.

Replace the parameters and options as needed for your specific use case.

Close Stories​

Terminate and close all playing stories or reels using the StorifyMe playback controller.

main.kt
StorifyMeSDK.instance.playbackController.closePlayback()

Make sure to use this feature judiciously, as it abruptly ends the playback without any specific user interaction. It is recommended to provide appropriate cues or user prompts before invoking this method to ensure a seamless and user-friendly experience.

Manage Seen State​

You can programmatically clear the seen state of stories in a widget — for example, after refreshing content or when you want users to be able to replay stories they have already watched.

Clear seen state for all stories:

main.kt
// Clear and immediately refresh the widget list
storiesView.clearAllSeenState()

// Clear without triggering a UI refresh
storiesView.clearAllSeenState(refreshList = false)

Clear seen state for a specific story:

main.kt
// Clear by experience ID and refresh the widget list
storiesView.clearSeenState(experienceId = 42L)

// Clear without triggering a UI refresh
storiesView.clearSeenState(experienceId = 42L, refreshList = false)
refreshList parameter

When refreshList is true (the default), the widget immediately re-sorts the visible list so cleared stories return to the unseen position. Pass false to skip the immediate update — the widget will reflect the cleared state the next time it is displayed or reloaded.

Open one experience by handle​

Use StorifyMeSDK.openExperienceByHandle to open an experience directly, without loading a widget first:

main.kt
StorifyMeSDK.openExperienceByHandle(
    context = this,
    handle = "summer-sale",
)

You can pass a StorifyMeWidgetConfig or StorifyMeExperienceBehaviour when the preview needs custom configuration or playback behavior.

Open experiences from a widget​

After the widget has loaded, use its experience navigator to open an item by position, handle, or ID. The optional behavior lets you set audio and playback behavior for that viewer session.

main.kt
storiesView.openWidgetExperienceByPosition(position = 0) { result ->
    when (result) {
        StorifyMeWidgetExperienceNavigatorExecutionResult.SUCCESS -> Unit
        StorifyMeWidgetExperienceNavigatorExecutionResult.NOT_FOUND -> showMissingExperienceMessage()
    }
}

storiesView.openWidgetExperienceByHandle(
    handle = "summer-sale",
    experienceBehaviour = StorifyMeExperienceBehaviour(
        audioBehaviour = StorifyMeExperienceAudioBehaviour.APPLY_CHANGE_FOR_PRESENTED_EXPERIENCES,
        playBackBehaviour = StorifyMeExperiencePlaybackBehaviour.ALWAYS_RESUME_EXPERIENCE_WHERE_STOPPED,
    ),
)

Use StorifyMeWidgetListener.onLoaded(widgetId, experiences) to access the loaded experience IDs and handles. The old openWidgetStoryBy... methods and StorifyMeWidgetStoryNavigatorExecutionResult remain deprecated compatibility APIs.

Accessibility​

Accessibility support​

The StorifyMe SDK provides accessibility support to ensure that your app is usable by people with disabilities. To enhance the accessibility of your app, you can follow these guidelines:

  1. Provide meaningful alternative text for images and other non-text content.
  2. Ensure that all interactive elements are accessible via touch or keyboard navigation.
  3. Use appropriate color contrast to ensure readability for users with visual impairments.
  4. Provide captions or transcripts for audio and video content.
  5. Use semantic markup to structure your content and make it easier to navigate with assistive technologies.

Set focus on an experience in a widget​

To set focus on a specific item in the StorifyMeWidget later, you can use the following code:

main.kt
storiesView.setFocusOnStoryItem(experienceId = 42L)

This focuses and scrolls to the widget item with that experience ID. The overload that accepts StoryWithSeen is deprecated; use the ID overload in new code.

By following these accessibility guidelines, you can ensure that your app is inclusive and accessible to all users, regardless of their abilities.