Skip to main content
Version: 3.x.x

Events

StorifyMe Android SDK 3 uses focused listener interfaces. Attach listeners to a StorifyMeWidget to keep callbacks scoped to that widget. Each listener has default no-op methods, so implement only the events your app needs.

Widget events​

StorifyMeWidgetListener reports loading, errors, size changes, scrolling, and content integrity failures.

val widget = findViewById<StorifyMeWidget>(R.id.storiesView)

widget.widgetListener = object : StorifyMeWidgetListener {
override fun onLoaded(widgetId: Long, experiences: List<StorifyMeExperience>) {
Log.d(TAG, "Loaded ${experiences.size} experiences for widget $widgetId")
}

override fun onFailed(error: StorifyMeError) {
Log.e(TAG, "Widget ${error.widgetId} failed: ${error.message}")
}
}

Experience lifecycle and navigation​

StorifyMeExperienceListener reports open, finish, close, share, and navigation events. Use navigationUrl to read the configured URL; it may be an app link or a web URL.

widget.experienceListener = object : StorifyMeExperienceListener {
override fun onOpened(experience: StorifyMeExperience, index: Int) {
analytics.track("experience_opened", experience.id)
}

override fun onFinished(experience: StorifyMeExperience, index: Int) {
analytics.track("experience_finished", experience.id)
}

override fun onNavigationRequested(
experience: StorifyMeExperience,
completion: (StorifyMeExperienceNavigationDecision) -> Unit,
) {
val url = experience.navigationUrl
if (url != null && myApp.canHandle(url)) {
myApp.navigate(url)
completion(StorifyMeExperienceNavigationDecision.HANDLE_NAVIGATION)
} else {
completion(StorifyMeExperienceNavigationDecision.OPEN_EXPERIENCE)
}
}
}

Call OPEN_EXPERIENCE to let the SDK open the experience, or HANDLE_NAVIGATION after your app handles the URL.

Content type​

Use StorifyMeExperienceType to branch on the content kind. Include UNKNOWN so your code has a fallback if the service adds a type in the future.

fun trackOpen(experience: StorifyMeExperience) {
when (experience.type) {
StorifyMeExperienceType.STORY -> analytics.track("story_opened", experience.id)
StorifyMeExperienceType.SHORTS -> analytics.track("short_opened", experience.id)
StorifyMeExperienceType.SNAP -> analytics.track("snap_opened", experience.id)
StorifyMeExperienceType.AD -> analytics.track("ad_opened", experience.id)
StorifyMeExperienceType.UNKNOWN -> Unit
// SHORT is a deprecated alias for SHORTS; omit it from new code.
}
}

See Experience data for the public fields available on StorifyMeExperience.

Ad events​

widget.adListener = object : StorifyMeAdListener {
override fun onAdDisplayed(experience: StorifyMeExperience, index: Int) {
adTracker.recordImpression(experience.id)
}
}

StorifyMeInteractionListener reports actions, analytics events, and links tapped inside the viewer.

widget.interactionListener = object : StorifyMeInteractionListener {
override fun onAction(action: StorifyMeInteractionAction) {
Log.d(TAG, "Action: ${action.type}")
}

override fun onEvent(event: StorifyMeInteractionEvent) {
analytics.track(event.action, event.rawData)
}

override fun onLinkTriggered(
url: String,
completion: (StorifyMeLinkTriggerCompletion) -> Unit,
) {
if (url.startsWith("myapp://")) {
myApp.navigate(url)
completion(StorifyMeLinkTriggerCompletion.IGNORE_PRESENTING_LINK)
} else {
completion(StorifyMeLinkTriggerCompletion.OPEN_LINK_BY_DEFAULT)
}
}
}

Commerce events​

widget.commerceListener = object : StorifyMeCommerceListener {
override fun onCartItemAdded(productId: String, quantity: Int) {
cart.add(productId, quantity)
}

override fun onCheckout(cart: StorifyMeCart) {
analytics.track("checkout", cart.total, cart.currency)
}
}

Migrating from 2.x​

The legacy StorifyMeEventListener and StorifyMeAdEventListener remain available with deprecation warnings during 3.x. New integrations should move to the focused listeners above. The v3 callbacks receive StorifyMeExperience, which replaces StoryWithSeen in the new listener APIs.

Legacy callbackV3 callback
onLoad(stories)StorifyMeWidgetListener.onLoaded(widgetId, experiences)
onStoryOpened(story, index)StorifyMeExperienceListener.onOpened(experience, index)
onStoryFinished(story, index)StorifyMeExperienceListener.onFinished(experience, index)
onStoryClosed(story)StorifyMeExperienceListener.onClosed(experience)
onStoryShared(story)StorifyMeExperienceListener.onShared(experience)
onStoryDeeplinkTriggered(story, completion)StorifyMeExperienceListener.onNavigationRequested(experience, completion)
onAdDisplayed(story, index)StorifyMeAdListener.onAdDisplayed(experience, index)