How to send analytics events through Flowbox's API

API endpoint

To send analytics data to Flowbox, a 'POST' request needs to be executed through this endpoint:

https://external-api.getflowbox.com/v1/analytics/event-tracking

Purpose

In order to have Analytics data available in Flowbox for your external API integration, you will need to handle the analytics events that the regular embed HTML Flows would trigger by firing them upon user visualization or interaction.

Each analytics event is meant for a specific purpose and as such they have different names.

Any event that is tracked needs to be assigned to a user-specific UUID, which is used as a value for the user_id field. This UUID needs to remain the same value during the a unique user's session in order to track each of the user's interactions separately. In embed HTML Flows, this is handled by generating a "_flowbox" cookie.

Required parameters

- api-key (header - string): This is your API authentication key, it must be included in the request header.

- Request body (application/JSON): can be different depending on the event that is being reported. Here's an example of its formatting:

{
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "from_url": "string",
  "data": {
    "event_name": "post_clicked",
    "flow_key": "string",
    "post_id": [
      "string"
    ]
  }
}

All events require the following fields within the request body. These are detailed under "BaseEvent":

user_id: User identifier. Needs to follow a UUID format, and is meant to identify the actions of each unique user. It needs to remain the same during each user's session.
from_url: URL from which the event was triggered from.
data: Event-specific data. Might require additional parameters depending on the event, but at the very least always requires the following ones:
- event_name: the name of the event ("embed_viewed", "post_clicked", "post_viewed"...)
- flow_key: the Flow key for which this event is being triggered.

List of events

It's not mandatory to integrate all the events listed below.

EVENT NAME	DESCRIPTION	REQUIRED DATA FIELDS
embed_viewed	when the image gallery is loaded and visible on a page.	`visible_post_ids` (Array comprised of strings): IDs for the posts that are in the viewport of a user
embed_load_more_clicked	when the 'Load more' button in the gallery is clicked. In case of unlimited scroll, can be triggered each time an additional page of content is loaded.	None
embed_carousel_next_post_clicked	for posts displayed on a "carousel" view, when a button is clicked on either side that allows the user to view more posts	None
post_clicked	when a post within the post gallery is clicked.	`post_id` (String): Post key for the post that has been clicked.
post_viewed	when a clicked post is displayed, allowing the user to view it within a gate or lightbox.	`post_id` (String): Post key for the post that has been viewed. `visible_product_keys` (Array comprised of strings): Keys of the products that are displayed next to the viewed post.
gate_next_post_clicked	when navigation buttons are clicked within the gate to navigate between posts.	None
post_carousel_next_media_clicked	when navigation buttons are clicked in a post with more than one photo or video ("carousel" posts).	`post_id` (String): Post key for the post whose images are being navigated.
cta_clicked	when a custom CTA button assigned to a post has been clicked	`post_id` (String): Post key for the post that is associated with this custom CTA button. `cta_type` (String): valid values are `product_cta`, `standalone_cta` or `flow_cta`. `product_key` (String): Product key for the product associated with the CTA click
checkout_conversion	when a customer finishes a purchase. It's meant to be executed right after every successful order. Allows to track Assisted Sales. For further reference on the structure, check "EventCheckoutConversion"	`conversion_type` (String): valid values are `purchase`, `booking`, `other`. `items` (Array comprised of Objects): List of purchased items. Requires `product_id`, `quantity`, `price` and `currency` for each item. `order_id` (String): Unique identifier of hte order associated with this checkout event. Following fields are only relevants for Ratings & Reviews users: `locale` (String): Locale for the language associated with this event. Used to set up the language for the Rating's email. `customer_data` (Array): customer's name & contact information. Used to reach out the customer with a review request. Can handle the following fields: `name`, `lastname`, `email` and `mobile`.

You can find more information and make test calls in our Swaggerhub page.