Events

You can attach and subscribe to events in order to run logic in your app when something happens in Stories. This way, you can:

• control what is shown,
• override events from StorifyMe stories,
• intercept click events and run internal logic,
• and many other use cases

Example code

The best way to attach listeners is by overriding native StorifyMe events:

  @override
  void onLoad(int widgetId, List<StorifyMeStory> stories) {
    debugPrint("onLoad: $stories");
  }

  @override
  void onFail(String exceptionMessage) {
    debugPrint("onFail: $exceptionMessage");
  }

  @override
  void onStoryOpened(StorifyMeStory story, int index) {
    debugPrint("onStoryOpened: $story");
  }

  @override
  void onStoryClosed(StorifyMeStory story) {
    debugPrint("onStoryClosed: $story");
  }

  @override
  void onAction(String type, String dataJson) {
    debugPrint("onAction: $type");
  }

  @override
  void onEvent(String type, String dataJson) {
    debugPrint("onAction: $type");
  }

  @override
  void onStoryShared(StorifyMeStory story) {
    debugPrint("onStoryShared: $story");
  }

  @override
  void onShopping(String type, String dataJson) {
    debugPrint('onShopping, type: $type, data: $dataJson');
  }

  @override
  Future<StorifyMeStoryDeeplinkTriggerCompletion> onStoryDeeplinkTriggered(
      StorifyMeStory? story) {
    debugPrint('onStoryDeeplinkTriggered: $story');
    return Future.value(
        StorifyMeStoryDeeplinkTriggerCompletion.openStoryByDefault);
  }

  @override
  Future<StorifyMeLinkTriggerCompletion> onLinkOpenTriggered(String url) {
    debugPrint('onLinkOpenTriggered: $url');
  
    return Future.value(StorifyMeLinkTriggerCompletion.openLinkByDefault);
  }
  

onLoad()

onLoad method is invoked when the widget loads successfully.

  @override
  void onLoad(int widgetId, StorifyMeStory story) {
    debugPrint("onLoad: $story");
  }

onFail()

onFail method is invoked when the widget loading fails. Use this even to for example hide the widget, or re-try loading.

  @override
  void onFail(String exceptionMessage) {
    debugPrint("onFail: $exceptionMessage");
  }

onStoryOpened()

onStoryOpened method is invoked any time a user opens a story.

  @override
  void onStoryOpened(StorifyMeStory story, int index) {
    debugPrint("onStoryOpened: $story");
  }

onStoryClosed()

onStoryClosed method is invoked when the user closes the story and the full screen preview.

  @override
  void onStoryClosed(StorifyMeStory story) {
    debugPrint("onStoryClosed: $story");
  }

onAction()

onAction method is invoked when the user engages with one of the engaging components. This way you can override for example a button click event and instead of opening the product details page on the website, you can open it in the app itself.

Or when they answer on the quiz question, based on the answer, you might want to send them to some specific page.

 @override
  void onAction(String type, String dataJson) {
    debugPrint("onAction: $type");
  }

onEvent()

onEvent method is invoked every time some analytics even is happening. It can be a slide view event, engaging element answer or similar.

Adding different analytics

While this method can be used to collect analytics on your side, we suggest adding the additional analytics processors in StorifyMe admin app under integrations.

  @override
  void onEvent(String type, String dataJson) {
    debugPrint("onAction: $type");
  }

onStoryShared()

onStoryShared method is invoked when the user shares the story.

  @override
  void onStoryShared(StorifyMeStory story) {
    debugPrint("onStoryShared: $story");
  }

onStoryShopping()

onStoryShopping method is invoked every time some cart manipulation is happening. Supported types: Supported types:

• CART_UPDATED - Happens every time cart is changed
• CART_ITEM_ADDED - Happens when a product is added to cart
• CART_ITEM_REMOVED - Happens when a product is removed from the cart
• CHECKOUT - Happens when user clicks on Checkout button in cart

  @override
  void onShopping(String type, String dataJson) {
    debugPrint('onShopping, type: $type, data: $dataJson');
  }

onStoryDeeplinkTriggered()

The onStoryDeeplinkTriggered method is designed to handle deep links triggered from a Story within the StorifyMe widget. This function provides developers with the ability to customize the behavior when a Story deep link is activated.

  @override
  Future<StorifyMeStoryDeeplinkTriggerCompletion> onStoryDeeplinkTriggered(
    StorifyMeStory? story) {
    debugPrint('onStoryDeeplinkTriggered: $story');
    return Future.value(
        StorifyMeStoryDeeplinkTriggerCompletion.openStoryByDefault);
  }

onLinkOpenTriggered()

The onLinkOpenTriggered method handles link openings within a Story, including links from Call to Action (CTA) buttons, product tags, deep links, and swipe-up actions. This function allows developers to customize how these links are processed when activated.

  @override
  Future<StorifyMeStoryDeeplinkTriggerCompletion> onStoryDeeplinkTriggered(
      if (checkSomeCondition) {
        // Prevent opening the link and handle manual link opening
        return Future.value(StorifyMeLinkTriggerCompletion.ignorePresentingLink);
      } else {
        // Proceed with the default link handling
        return Future.value(StorifyMeLinkTriggerCompletion.openLinkByDefault);
      }
  )

If you need additional information about the link, you can retrieve it from the onAction event. For example, if you want to identify whether the triggered link is a CTA button, a product tag, or another link type, you can access this information in the onAction event. The onAction event is triggered first, followed by the onLinkOpenTriggered event.

Additionally, if you don't specify any conditions, the settings will apply to all links. For example, if you return Future.value(StorifyMeLinkTriggerCompletion.ignorePresentingLink); without any conditions, this will prevent all links from being opened within the story, regardless of their type.

Below is an example of how to get the type of the triggered element.

Click to view full code

  String? elementType;
  String? buttonValue;
  
  @override
  void onAction(String type, String dataJson) {
    try {
      // Extract "data" object
      final Map<String, dynamic> dataMap = jsonDecode(dataJson);
  
      // Extract the element type (e.g., BUTTON, PRODUCT_TAG, etc.)
      elementType = dataMap['type'] as String?;
  
      // Extract button value
      final dataSection = dataMap['data'] as Map<String, dynamic>?;
      buttonValue = dataSection?['value'] as String?;
    } catch (e) {
      elementType = null;
      buttonValue = null;
    }
  }
  
  @override
  Future<StorifyMeLinkTriggerCompletion> onLinkOpenTriggered(String url) {
    // Declare a late Future variable to hold the completion result;
    late Future<StorifyMeLinkTriggerCompletion> completionFuture;
  
    // Example condition, can be replaced with your own logic
    final checkSomeCondition = (elementType == 'BUTTON' && buttonValue == url);
  
    if (checkSomeCondition) {
      // Prevent opening the link and handle manual link opening
      completionFuture = Future.value(StorifyMeLinkTriggerCompletion.ignorePresentingLink);
    } else {
      // Proceed with the default link handling
      completionFuture = Future.value(StorifyMeLinkTriggerCompletion.openLinkByDefault);
    }
  
    // Reset values after handling the link open trigger
    elementType = null;
    buttonValue = null;
  
    // Return the prepared Future after resetting values.
    return completionFuture;
  }