Configuration

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

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.

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. It can be easily adjusted by setting StoryAudioBehaviour.

• 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.
• APPLY_CHANGE_FOR_PRESENTED_STORIES - The same behaviour will be applied on every story launch, no matter what user done in past. When a user mutes/unmutes a story, that change will be applied for all stories that are currently listed in widget. After user dismisses stories, and presents them again, the default behaviour will be applied.

main.kt

storiesView.setAudioOptions(
    StoryAudioBehaviour.APPLY_LAST_USER_CHANGE_FOR_ALL_FUTURE_STORIES,
    defaultState = StoryAudioState.MUTED)

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<StoriesView>(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()

Configure Language for Widget

The desired language for the StorifyMe widget can be specified using the setLanguage method by providing a valid language code.

main.kt

val storiesView = findViewById<StoriesView>(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()

Disable initial onboarding screen

You can hide the onboarding screen with a simple call method:

main.kt

  StorifyMe.instance.disableInitialOnboarding()

Disable tutorial screen

Use this method to permanently disable the initial onboarding tutorial, ensuring users won't encounter it again after it's triggered.

main.kt

StorifyMe.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

StorifyMe.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

StorifyMe.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

StorifyMe.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

StorifyMe.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.

Open a single story by handle

It's possible to open a single specific StorifyMe story by handle programmatically, here is the example code:

import com.storify.android_sdk.PreviewStoryByHandleLauncher

Then, in order to launch the specific story with handle some-example-handle all that needs to be done is to run this line of code:

findViewById<Button>(R.id.btnOpenHandle).setOnClickListener {
    PreviewStoryByHandleLauncher.INSTANCE.launch(this, "some-example-handle")
}

Open stories manually

You can also load a story right away after the page is loaded. This way, the first thing a user sees is the story. To do so, you can have a loading animation while stories load, and then once stories are loaded you can just open a story by ID, handle or position.

And then using the code you can open a specific story by:

• position
• handle
• id as explained in the following sections.

This is done via StorifyMeWidgetStoryNavigator interface, facilitating the targeted opening of specific stories within your widget.

openWidgetStoryByPosition()

You can open a story from the widget directly from the code. To open the first story in the Widget list of stories, please use:

main.kt

storiesView.openWidgetStoryByPosition(position: Int, completion: ((StorifyMeWidgetStoryNavigatorExecutionResult) -> Unit)?)

How to get list of stories?

You can get length of stories in widget, as well as their IDs and handles from the onLoad callback.

openWidgetStoryByHandle()

You can open a story by handle from the widget directly from the code. To open the story with the handle story-handle from the Widget list of stories, please use:

main.kt

storiesView.openWidgetStoryByHandle(handle: String, completion: ((StorifyMeWidgetStoryNavigatorExecutionResult) -> Unit)?)

openWidgetStoryById()

You can open a story by ID from the widget directly from the code. To open the story with the ID 1 from the Widget list of stories, please use:

main.kt

storiesView.openWidgetStoryById(id: Long, completion: ((StorifyMeWidgetStoryNavigatorExecutionResult) -> Unit)?)

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 a story in a widget

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

main.kt

storiesView.setFocusOnStoryItem(story)

Replace story with the desired item to set focus on. This can help users with visual impairments navigate through the stories more easily.

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