Skip to main content

Single Story

Used to display stories by their id or slug.

Presentation​

Remark
If the settings parameter was not specified for InAppStory before showing single story, it should be set:

InAppStory.shared.settings = Settings(userID: <String>, tags: <Array<String>?>)

To display single story, you need call the showStory method of the singleton class InAppStory.shared:

InAppStory.shared.showStory(with id: <String>, from target: <UIViewController>, with panelSettings: <PanelSettings>? = nil, with panelSettings: PanelSettings? = nil, complete: <()->Void>) -> CancellationToken?

Parametr panelSettings displaying the bottom bar (overwrite InAppStory.shared.panelSettings) <PanelSettings>; (Details)

Remark
Starting from version 1.27.0, the method returns CancellationToken? which allows cancelling the operation. For more details, see Cancellation of actions.

To close the reader of single story, call closeReader(complete: () -> Void). This may be necessary, such as when handling open the link by push a button in story. complete called after closing the reader.

Showing by ID with targeting​

Available since SDK 1.29.9 (4370). Use showStoryWithTargeting(with:from:with:tags:complete:) to request a single story by ID with server-side targeting checks:

InAppStory.shared.showStoryWithTargeting(
    with: "<storyID>",
    from: self,
    tags: ["promo"]
) { show in
    // true if the story reader was shown; false if no eligible story was shown
}
  • with id: String and from target: UIViewController identify the story and presenting controller.
  • with panelSettings: PanelSettings? = nil uses the same panel settings rules as showStory.
  • tags: [String]? = nil uses the current SDK settings' tags. Pass [] to send an empty tag list, or an explicit array to override tags for this request without changing SDK settings. The usual tag validation and limits apply.
  • complete: (Bool) -> Void is required and reports whether the reader was shown.
  • The method returns CancellationToken?; see cancellation.

Targeting is enabled by choosing this method, including when tags is left at nil. Existing showStory, showStoryOnce, and SwiftUI .singleStory(...) calls keep their behavior from before 1.29.9; updating the SDK does not enable targeting for them.

The targeted request also includes the current options[OptionsKeys.POS], if set; see request options. For integrations already using the IAS_API SPI, InAppStoryAPI.shared.singleStoryAPI.showStoryWithTargeting(with:with:tags:complete:) has the same defaults and obtains the presenting controller automatically. If it cannot find a controller, it returns nil and calls complete(false). The ordinary SwiftUI .singleStory(...) modifier has no targeting parameter.

Sample (SingleStory)​

This type of story is opened by the specified id or slug. It can be used open from a push notification or be tied to an entity in an app (like a poll or trailer).

To display single story, you need to initialize InAppStory library in the project.

AppDelegate.swift​

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool
{
    // library initialization
    InAppStory.shared.initWith(serviceKey: <String>)

    // settings can also be specified at any time before creating a StoryView or calling individual stories
    InAppStory.shared.settings = Settings(userID: <String>, tags: <Array<String>>)

    return true
}

In the controller, where it is necessary to show a single story, call the showStory method on InAppStory.

ViewController.swift​

...

func pushNotification() {
    InAppStory.shared.showStory(with: <String>, from: <UIViewController>, with: <PanelSettings>?) { show in
        // the closure is triggered when the single story reader is opened
        // show: <Bool> - if the reader was presented on the screen, value is true
    }
}
...

To track actions of the single story reader, you need to implement InAppStoryDelegate methods:

ViewController.swift​

extension ViewController: InAppStoryDelegate
{
    func storiesDidUpdated(isContent: Bool, from storyType: StoriesType) {
        // called when the contents of the list are updated
    }

    // called when a button or SwipeUp event is triggered in the reader
    func storyReader(actionWith target: String, for type: ActionType, from storyType: StoriesType) {
        if type == .swipe { // link obtained by swipeUP action
           if let url = URL(string: target) {
               let swipeContentController = SwipeContentController()
               // passing link to controller with WebView
               swipeContentController.linkURL = url

               if storyType == .single {
                // opening the controller on top of the reader
                InAppStory.shared.singlePresent(controller: swipeContentController)
               }
           }
       } else { // .button, .game, .deeplink
            // if the processed link leads to a screen in the application,
            // it is recommend to close the reader
            InAppStory.shared.closeReader {
                // processing a link, for example, to follow it in safari
                if let url = URL(string: target) {
                    UIApplication.shared.open(url, options: [:], completionHandler: nil)
                }
            }
        }
    }

    func storyReaderWillShow(with storyType: StoriesType) {
        // called before the reader will show
    }

    func storyReaderDidClose(with storyType: StoriesType) {
        // called after closing the story reader
    }
}

v.1.22.0​

In version 1.22.0 you can now use one general method present for displaying the controller over readers instead of the remote.

Remote method (old)​

InAppStory.singleStoryPresent(controller presentingViewController: UIViewController, with transitionStyle: UIModalTransitionStyle = .coverVertical)

General method (new)​

/// Displaying the modal controller on top of the stories reader
/// - Parameters:
///   - presentingViewController: displayed controller
///   - presentationStyle: display style, defaults to .overCurrentContext
///   - transitionStyle: display animation style, default is .coverVertical
func present(controller presentingViewController: UIViewController,
             for presentationStyle: UIModalPresentationStyle = .overCurrentContext,
             with transitionStyle: UIModalTransitionStyle = .coverVertical)

Panel Settings​

To set special settings for the bottom bar in single story. You must specify the panelSettings parameter when calling the showStory(...) method.

InAppStory.shared.showStory(with: "<storyID>",
                            from: self, // target from where the reader will be shown
                            with: PanelSettings(like: true, favorites: true, share: true)) // custom panel settings
{ _ in
    // closure after showng reader
}
warning

InAppStoryDelegate is currently considered deprecated, and it's methods were carried over as InAppStory class closures.

Follow this guide to configure single story link handling.

Show story once​

Starting with SDK version 1.23.0 we have added the ability to display a single story only once (similar to onboarding). In this scenario, a story will be shown if it has not been requested by a particular user. In scenarios where the application has a list or shows onboarding, reading the story in one of the sources will be blocked in the InAppStory.shared.showStoryOnce method.

To show a single story by id, with the ability to display it only once, you need to call the InAppStory.shared.showStoryOnce(...) method:

InAppStory.shared.showStoryOnce(with: "<storyID>",
                                from: self, // target from where the reader will be shown
                                with panelSettings: PanelSettings(like: true, favorites: true, share: true)) // single story delegate
{ _ in
    // closure after showng reader
}