Event Handling Overview

The 5 Primary Events

The Flagship SDK communicates with your app via a delegate pattern. There are 5 primary events that it might generate:

Show Story
Close Story
Deeplink
Analytics
Error

Android Delegate

The Android SDK provides a FlagshipDelegate interface that defines the methods that should be implemented:

interface FlagshipProviderDelegate {
    fun handleShowStory(postID: String)
    fun handleCloseStory(postID: String)
    fun handleDeeplink(uri: String)
    fun handleAnalytics(postID: String, title: String, action: String, url: String, eventID: String)
    fun handleError(errorCode: FlagshipErrorType)
}

Your implementation of the delegate can be registered using FlagshipService:

FlagshipService.getShared().delegate = myDelegate

For convenience, you may also set the delegate while building the FlagshipFeedIntent and FlagshipStoryIntent:

val intent = FlagshipStoryIntent.Builder(this@MainActivity)
    .setDelegate(myDelegate)
    .build()

iOS Delegate

The iOS SDK provides a FlagshipDelegate protocol that defines the methods that should be implemented:

public protocol FlagshipDelegate: NSObjectProtocol {
    func handleShowStory(postID: String)
    func handleCloseStory(postID: String)
    func handleDeeplink(uri: String)
    func handleAnalytics(postID: String, title: String, action: String, url: String, eventID: String)
    func handleError(errorCode: FlagshipErrorType)
}

Your implementation of the delegate can be registered to the FlagshipFeedViewController and/or FlagshipStoryViewController:

let feedViewController = FlagshipFeedViewController.init()
feedViewController.delegate = MyDelegate

React Native Event Handlers

Your event handlers can be provided as properties to the Flagship() initializer:

const { FlagshipFeed, FlagshipStory, FlagshipService } = Flagship({
    ...
    handleShowStory: handleShowStory,
    handleCloseStory: handleCloseStory,
    handleDeeplink: handleDeeplink,
    handleAnalytics: handleAnalytics,
    handleError: handleError
});

You may also provide them as optional properties to the FlagshipFeed and/or FlagshipStory components:

return (
    <FlagshipFeed
        handleShowStory={handleShowStory}
        handleCloseStory={handleCloseStory}
        handleDeeplink={handleDeeplinkEvent}
        handleAnalytics={handleAnalyticsEvent}
        handleError={handleErrorEvent}
    />
);

The React Native SDK will call the most specific event handler; for example, an instance of the FlagshipFeed component will call its own handleShowStory callback if one is provided, otherwise it will call the handler provided to the Flagship() initializer.

Show Story Event

Overview

A show story event is invoked when a user taps on a Post that contains a Story. It is then the responsibility of the app to navigate the user to an instance of the Story Controller. See Displaying a Story.

Android

override fun handleShowStory(postID: String) {
    // Here you should navigate the user to the correct location
    // in your app where you'd like stories to appear and pass
    // the postID
    val storyIntent = FlagshipStoryIntent.Builder(this@MainActivity)
        .setPostID(postID)
        // Optional - register a delegate to handle events from the user interacting with the story
        .setDelegate(myDelegate)
        .build()
}

handleShowStory is a method defined as part of the FlagshipDelegate interface. Your implementation of the protocol can be set as the delegate using FlagshipService or in the FlagshipFeedIntent or FlagshipStoryIntent:

FlagshipService.getShared().delegate = myDelegate
// or
val intent = FlagshipStoryIntent.Builder(this@MainActivity)
    .setDelegate(myDelegate)
    .build()

iOS

func handleShowStory(postID: String) {
    // Here you should navigate the user to the correct location
    // in your app where you'd like stories to appear and pass
    // the postID to a FlagshipStoryViewController
    let storyViewController = FlagshipStoryViewController.init(postID: postID)
    // Display storyViewController however you'd like. Typically by pushing
    // it onto the navigation stack
}

handleShowStory is a method defined as part of the FlagshipDelegate protocol. Your implementation of the protocol can be set as the delegate in the FlagshipFeedViewController or FlagshipStoryViewController:

let feedViewController = FlagshipFeedViewController.init()
feedViewController.delegate = MyDelegate

React Native

function handleShowStory(postID: string) {
    // Here you should navigate the user to the correct location
    // in your app where you'd like stories to appear and pass
    // the postID to a FlagshipStory component.
}

You can register this function when initializing Flagship:

const { FlagshipFeed, FlagshipStory, FlagshipService } = Flagship({
    ...
    handleShowStory: handleShowStory
});

Or you can pass it as a prop to a FlagshipFeed component:

return (
    <FlagshipFeed handleShowStory={handleShowStory} />
);

Close Story Event

Overview

A close story event is invoked when the user taps a "close" button within a Story. When this is triggered it's the app's responsibility to navigate the user back to their previous place in the navigation stack or to a different screen.

Android

override fun handleCloseStory(postID: String) {
    // Here you navigate the user back to where they previously
    // were in the navigation stack (e.g. if displaying the story as
    // a modal, close the modal).
}

handleCloseStory is a method defined as part of the FlagshipDelegate interface. Your implementation of the protocol can be set as the delegate using FlagshipService or in the FlagshipFeedIntent or FlagshipStoryIntent:

FlagshipService.getShared().delegate = myDelegate
// or
val intent = FlagshipStoryIntent.Builder(this@MainActivity)
    .setDelegate(myDelegate)
    .build()

iOS

func handleCloseStory(postID: String) {
    // Here you navigate the user back to where they previously
    // were in the navigation stack (e.g. if displaying the story as
    // a modal, close the modal).
}

handleCloseStory is a method defined as part of the FlagshipDelegate protocol. Your implementation of the protocol can be set as the delegate in he FlagshipFeedViewController or FlagshipStoryViewController:

let feedViewController = FlagshipFeedViewController.init()
feedViewController.delegate = MyDelegate

React Native

function handleCloseStory(postID: string) {
    // Here you navigate the user back to where they previously
    // were in the navigation stack (e.g. if displaying the story as
    // a modal, close the modal).
}

You can register this function when initializing Flagship:

const { FlagshipFeed, FlagshipStory, FlagshipService } = Flagship({
    ...
    handleCloseStory: handleCloseStory
});

Or you can pass it as a prop to a FlagshipStory component:

return (
    <FlagshipStory handleCloseStory={handleCloseStory} />
);

Deeplink Event

Overview

Deeplinks are a type of links that send users directly to an app instead of a website. Deeplinks are used to send users to specific screens, which could tie into a specific campaign you are running, thus significantly improving user experience and user engagement.

In Flagship, deeplink events are invoked when a user taps a Post or Story within an app that contains a deeplink to a different location. The SDK will provide the URL but it's the host app's responsibility to navigate the user to the correct place within the app or externally.

Android

override fun handleDeeplink(uri: String) {
    // Here you process the URI and navigate the user to the correct
    // location. We recommend passing this URI to your app's universal
    // link handler. Note: this URI might be an external link (e.g. mailto:)
}

handleDeeplink is a method defined as part of the FlagshipDelegate interface. Your implementation of the protocol can be set as the delegate using FlagshipService or in the FlagshipFeedIntent or FlagshipStoryIntent:

FlagshipService.getShared().delegate = myDelegate
// or
val intent = FlagshipStoryIntent.Builder(this@MainActivity)
    .setDelegate(myDelegate)
    .build()

iOS

func handleDeeplink(uri: String) {
    // Here you process the URI and navigate the user to the correct
    // location. We recommend passing this URI to your app's universal
    // link handler. Note: this URI might be an external link (e.g. mailto:)
}

handleDeeplink is a method defined as part of the FlagshipDelegate protocol. Your implementation of the protocol can be set as the delegate in the FlagshipFeedViewController or FlagshipStoryViewController:

let feedViewController = FlagshipFeedViewController.init()
feedViewController.delegate = MyDelegate

React Native

function handleDeeplink(uri: string) {
    // Here you process the URI and navigate the user to the correct
    // location. We recommend passing this URI to your app's universal
    // link handler. Note: this URI might be an external link (e.g. mailto:)
}

You can register this function when initializing Flagship:

const { FlagshipFeed, FlagshipStory, FlagshipService } = Flagship({
    ...
    handleDeeplink: handleDeeplink
});

Or you can pass it as a prop to a FlagshipFeed or FlagshipStory component:

return (
    <FlagshipFeed handleDeeplink={handleDeeplink} />
);

Analytics Event

Overview

Analytic events are invoked whenever a user performs an action, such as tapping on a Post. They can be used to send data to an analytics provider. Flagship account managers can add tags to elements to uniquely identify them.

Event Arguments

The following arguments are provided to the analytics handler:

postID: The ID of the Post in which the user interacted
title: The title of the Post in which the user interacted
action: The user action that triggered the analytics event. The most common action types are "deep-link" (to indicate that a user tapped on a deeplink) and "story" (to indicate that a user viewed a Story)
url: The relevant URL, for example when a user taps on a deeplink
eventID: This is the optional custom identifier that can be provided to buttons, links, and similar elements within the Feeds UI to indicate what element within a Feed a user interacted with

Note that not all arguments are relevant to every event and will be set to nil/null when not applicable.

Android

override fun handleAnalytics(
    postID?: String,
    title?: String,
    action?: String,
    url?: String,
    eventID?: String
) {
    // Here you can process the analytics event. For example,
    // forwarding it to your preferred analytics vendor.
}

handleAnalytics is a method defined as part of the FlagshipDelegate interface. Your implementation of the protocol can be set as the delegate using FlagshipService or in the FlagshipFeedIntent or FlagshipStoryIntent:

FlagshipService.getShared().delegate = myDelegate
// or
val intent = FlagshipStoryIntent.Builder(this@MainActivity)
    .setDelegate(myDelegate)
    .build()

iOS

func handleAnalytics(
    postID: String?,
    title: String?,
    action: String?,
    url: String?,
    eventID: String?
) {
    // Here you process the analytics event. For example,
    // forwarding it to your preferred analytics vendor.
}

handleAnalytics is a method defined as part of the FlagshipDelegate protocol. Your implementation of the protocol can be set as the delegate in the FlagshipFeedViewController or FlagshipStoryViewController:

let feedViewController = FlagshipFeedViewController.init()
feedViewController.delegate = MyDelegate

React Native

function handleAnalytics(
    postID: string,
    title: string,
    action: string,
    url: string,
    eventID: string
) {
    // Here you process the analytics event. For example,
    // forwarding it to your preferred analytics vendor.
}

const { FlagshipFeed, FlagshipStory, FlagshipService } = Flagship({
    ...
    handleAnalytics: handleAnalytics
});

Or pass it as a prop to a FlagshipFeed or FlagshipStory component:

return (
    <FlagshipFeed handleAnalytics={handleAnalytics} />
);

Note: We recommend using this event to track events with your preferred analytics vendor. See Integrating Analytics.

Error Event

Overview

Error events are invoked when the Flagship API returns a critical error, such as being provided an invalid App ID or a server error. Recommendations on what to do with errors can be found in the Error Handling section.

Android

override fun handleError(errorCode: FlagshipErrorType) {
    // Here you process the error event and display the appropriate
    // messaging or fallback content.
}

handleError is a method defined as part of the FlagshipDelegate interface. Your implementation of the protocol can be set as the delegate using FlagshipService or in the FlagshipFeedIntent or FlagshipStoryIntent:

FlagshipService.getShared().delegate = myDelegate
// or
val intent = FlagshipStoryIntent.Builder(this@MainActivity)
    .setDelegate(myDelegate)
    .build()

Types of Errors:

The provided FlagshipErrorType enum can be one of the following:

NO_APP_ID
- No Flagship Application ID was provided to the SDK.
- Refer to the Installation Instructions section for how to provide the App ID.
INVALID_APP_ID
- The Application ID provided was not valid with the Flagship API.
- Contact Branding Brand for more information.
EMPTY_FEED
- The Flagship API successfully completed but returned no messages.
- This is most likely caused by segmented messages that don't match the current user profile.
FETCH_FEED_ERROR
- An error occurred communicating to the Flagship API.
- Possible causes include network issues or a server error.
INVALID_POST_ID
- The app attempted to render a specific Story, but the provided Post ID does not exist in the Feed.

iOS

func handleError(errorCode: FlagshipErrorType) {
    // Here you should process the error event and display the appropriate
    // messaging or fallback content.
}

handleError is a method defined as part of the FlagshipDelegate protocol. Your implementation of the protocol can be set as the delegate in the FlagshipFeedViewController or FlagshipStoryViewController:

let feedViewController = FlagshipFeedViewController.init()
feedViewController.delegate = MyDelegate

Types of Errors:

The provided FlagshipErrorType enum can be one of the following:

.noAppID

No Flagship Application ID has been provided to the SDK.Refer to the Installation Instructions section for how to provide the App ID..invalidAppID
The Application ID provided is not currently valid with the Flagship API.
Contact Branding Brand for more information.

.emptyFeed

The Flagship API successfully completed but returned no messages.
This is most likely caused by segmented messages that don't match the current user profile.

.fetchFeedError

This is invoked whenever an error occurs communicating to the Flagship API.
Possible causes include network issues or a server error.

.invalidPostID

This is invoked when attempting to render a specific Story but the provided Post ID does not exist in the Feed.

React Native

function handleError(errorCode: FlagshipError) {
    // Here you should process the error event and display the appropriate
    // messaging or fallback content.
}

You can register this function when initializing Flagship:

const { FlagshipFeed, FlagshipStory, FlagshipService } = Flagship({
    ...
    handleError: handleError
});

Or you can pass it as a prop to a FlagshipFeed or FlagshipStory component:

return (
    <FlagshipFeed handleError={handleError} />
);

Types of Errors:

The provided FlagshipError can be one of the following:

NO_APP_ID

No Flagship Application ID has been provided to the SDK.
Refer to the Installation Instructions section for how to provide the App ID.

INVALID_APP_ID

The Application ID provided is not currently valid with the Flagship API.
Contact Branding Brand for more information.

EMPTY_FEED

The Flagship API successfully completed but returned no messages.
This is most likely caused by segmented messages that don't match the current user profile.

FETCH_FEED_ERROR

This is invoked whenever an error occurs communicating to the Flagship API.
Possible causes include network issues or a server error.

INVALID_POST_ID

This is invoked when attempting to render a specific Story but the provided Post ID does not exist in the Feed.

Did this answer your question?