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)
}
}
Interaction and link events
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 callback | V3 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) |