Skip to main content

Configuration

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

Configuration​

Widget Properties​

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

storifyMeWidget.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 PlaybackBehaviour behavior.

  • restartStoriesOnAppLaunch - On every app launch, all stories will start from beginning
  • restartStoriesWhenOpen - On every stories preview launch, all stories will start from beginning
  • alwaysResumeStoryWhereStopped - Stories will resume where user previously stopped watching them, no matter if app was earlier terminated or stories closed
storifyMeWidget.setPlaybackOptions(
  options: StorifyMeStoryPlaybackOptions(
    behaviour: .restartStoriesOnAppLaunch
  )
)

Configure Audio control​

Audio control of stories can be customized. It can be easily adjusted by setting StorifyMeStoryAudioOptions.

  • applyLastUserChangeForAllFutureStories - 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.
  • applyChangeForSingleStory - 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.
  • applyChangeForPresentedStories - 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.
storifyMeWidget.setWidgetAudioOptions(
                options: StorifyMeStoryAudioOptions(
                    behaviour: .applyLastUserChangeForAllFutureStories,
                    defaultState: .unmuted))

Configure URL Presentation Control​

The StorifyMeURLPresentationOptions 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.

PresentationMode

  • inAppBrowser: URLs are presented within an in-app browser. User interactions with URLs are maintained across successive story presentations, ensuring consistent behavior.
  • externalBrowser (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 StorifyMeURLPresentationOptions accordingly.

Example usage:

storifyMeWidget.setURLPresentationOptions(
  options: StorifyMeURLPresentationOptions(presentationMode: .inAppBrowser))

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:

storifyMeWidget.setWidgetScrollNavigationOptions(
    options: StorifyMeWidgetScrollNavigationOptions(   
        storiesNavigation: .verticalCenteredControls))

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.
var config = StorifyMeWidgetConfig()
// Set direction to Right-to-Left (RTL)
config.setDirection(direction: StorifyMeContentDirection.rtl) 

let storifyMeWidget = StorifyMeWidget()
storifyMeWidget.setWidgetConfig(config: config)
storifyMeWidget.setWidgetId(widgetId: WIDGET_ID)
storifyMeWidget.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.

var config = StorifyMeWidgetConfig()
// Set the language to English
config.setLanguage(languageCode: "en")

let storifyMeWidget = StorifyMeWidget()
storifyMeWidget.setWidgetConfig(config: config)
storifyMeWidget.setWidgetId(widgetId: WIDGET_ID)
storifyMeWidget.load()

Disable initial onboarding screen​

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

  StorifyMe.instance.disableInitialOnboarding()

Disable Tutorial​

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

StorifyMeInstance.shared.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:

StorifyMeInstance.shared.showNotification(
            title: "Notification title example",
            message: "Message example")

Replace the parameters with the desired title, message and optional 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:

StorifyMeInstance.shared.playbackController.pausePlayback(controlsVisibility: .visible)

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

To Resume Playback:

StorifyMeInstance.shared.playbackController.resumePlayback(mode: .fromBeginning)

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.

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

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:

  StorifyMeInstance.shared.openStoryByHandle(handle: "some-example-handle")

In case you want to define the button (or similar) via code, you can do this:

override func viewDidLoad() {
  super.viewDidLoad()
  ...
  setupOpenByHandleButton()
}

private func setupOpenByHandleButton() {
  let button = UIButton()
...
  button.addTarget(self, action: #selector(openByHandleButtonTapped), for: .touchUpInside)
...
}

@objc private func openByHandleButtonTapped() {
  StorifyMeInstance.shared.openStoryByHandle(handle: "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.

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:

storifyMeWidget.openWidgetStoryByPosition(_ position: Int, completion: ((StorifyMeWidgetStoryNavigatorExecutionResult) -> Void)?)
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:

storifyMeWidget.openWidgetStoryByHandle(_ handle: String, completion: ((StorifyMeWidgetStoryNavigatorExecutionResult) -> Void)?)

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:

storifyMeWidget.openWidgetStoryById(_ id: Int, completion: ((StorifyMeWidgetStoryNavigatorExecutionResult) -> Void)?)

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:

storifyMeWidget.setFocusOnStoryCell(story)

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

Focus a story cell when using an external keyboard​

If you need to focus a story cell while an external keyboard is used, check the approach below:

Click to view the full code
let storifyMeWidget = StorifyMeWidget()
var cellToFocus: UICollectionViewCell? = nil // Variable to store the cell to focus on

// Function to focus on a specific story cell
private func focusCell(story: story) {
    // Set focus on the specified story
    storifyMeWidget.setFocusOnStoryCell(story: story) { cell in
        // Completion handler: once focus is set, check if the cell is returned
        if let cell = cell {
            // Store the focused cell if available
            self.cellToFocus = cell
        } else {
            // If no cell is returned, reset the focus variable
            self.cellToFocus = nil
        }
        
        // Request a focus update and ensure the focus is updated immediately
        self.setNeedsFocusUpdate()
        self.updateFocusIfNeeded()
    }
}

// Override to return the custom cell for focus if available
// If no custom cell is set, fall back to the default preferred focus environments
override var preferredFocusEnvironments: [UIFocusEnvironment] {
    // Check if a custom cell is set for focus
    if let cell = cellToFocus {
        // Reset the focus variable after using the custom cell
        cellToFocus = nil
        // Return the custom cell as the preferred focus environment
        return [cell]
    } else {
        // Fallback to the default preferred focus environments if no custom cell is set
        return super.preferredFocusEnvironments
    }
}

focusCell(story:)​

focusCell(story:): This function sets focus on a specific story by passing the story object. It uses a completion handler to ensure that the focus update is performed only after the story's focus action has completed. If the focus is set successfully, it stores the corresponding UICollectionViewCell in the cellToFocus variable.

preferredFocusEnvironments​

preferredFocusEnvironments: This override ensures that the custom UICollectionViewCell is used as the preferred focus environment. If no custom focus is set (i.e., cellToFocus is nil), it defaults to the standard behavior.

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