Flagship Integrated Analytics

Overview

Documentation updated to reflect SDK 1.17.0 updates.

Analytics is critical to the success of our content and our apps. It's as integral to a business as having a website in this day and age. With that in mind, we have implemented a simple but powerful analytics-based feature to help your success.

Goals

Goals track actions users take in your app. Goals can be based on users viewing posts, deep links, or triggering a particular event such as a tap on a specific post.

Based on our extensive, battle-tested experience in e-commerce, we have predefined the following goals for you:

Post Impressions
Deep Links
Story Views
Tap Events
Sales

Post Impressions

These are views on posts. It's considered a view when the post has been displayed entirely on the user's screen.

Deep Links

Deep Links take you further into the content. Instead of just taking users to a general tab within the app, deep links take the user to a specific section in that tab. This goal shows you how many of those deep links have been used.

Story Views

Flagship Stories are powerful tools to house your content. It allows you to tell more of your brand's story. By default, we'll track how many Story Views your app gets.

Tap Events

It's important to know what content and which links are interacted with. We track Tap Events by default in Flagship's Integrated Analytics feature.

Sales

This is the total amount of revenue that has been tracked by events that are registered by your developer.

Information Collected

The information that is collected for each of the above goals (except for Sales) includes:

Post Title
Post Identifier
Feed Type (stacked vs. scrollable)
Component Identifier (Note: this information is useful for developers only in the case of debugging)

Please note: Sales is a special case that does not collect the above information. The information sent to Sales is the revenue logged with the event your developer will setup. Additional information can be sent. Please discuss this with your development team.

Unique Visitors

Unique Visitors are the number of people who visited your Feed. We are privacy-friendly so we don't use cookies and other persistent identifiers. If a person visits from multiple devices or on multiple days, they are counted as separate visitors.

We do not attempt to generate a device-persistent identifier because they are considered personal data under GDPR. We do not use cookies, browser cache, or local storage. We do not store, retrieve or extract anything from visitor's devices.

For Developers:

Every single HTTP request sends the IP address and the User-Agent to the server - so that's what we use. We generate a daily changing identifier using the visitor's IP address and User-Agent. To anonymize these data points and make them impossible to relate back to the user, we run them through a hash function with a rotating salt.

Conversion Rate

The Conversion Rate is the percentage of visitors who visit your Flagship Feed and checkout or hit an area where your development team has logged the track conversion event. This is the number of unique visitors divided by track conversion events that are set up by your developer.

Page Views

Page Views are automatically sent with any event. With our SDK, developers send an event in your app and when they do they include a special URL that represents the section of where your user is at. You'll see these show up in your dashboard.

For Developers:

Page Views are a custom URL we build to assign more meaning to where and how events are triggered when looking at the dashboard.

All URLs should start with /flagship in addition custom properties like feedType and postTitle are expected to construct this URL!

Example:

/flagship/:feedType/:postTitle

Views Per Visit (or Pages / Session)

Views per visit (also known as Pages per session) show the average number of page views per visit. Repeated views of a single page are included too.

Visit Duration

The amount of time visitors spend on your site. It only shows people who visit more than one page. For those who visit one page only we default to 0 seconds. Average visit duration is the sum of all session lengths divided by the number of sessions, which includes the 0-second visits (bounces).

If you have issues with high bounce rates on your site, you can try to set up some custom events. All custom events are considered interactive so any clicks on those events will count towards the bounce rate and visit duration too.

Viewing Analytics

Simply login to https://flagship.brandingbrand.com

You can access Viewing Analytics via the analytics tab under "Audiences" in the left panel navigation.

Custom Analytics Calls

It's possible to create custom events that aren't listed above. If you don't have a particular use case for this, you can skip this section, but it's good to know that you can have custom events—one such example may be to track newsletter sign-ups.

The next sections are intended for your development team to set up custom events.

Note: the next sections Custom Click Event and Conversion Tracking must be used within Flagship portals!

Please see the portals section of the docs to see how portals are setup. The SDK exposes a way for clients to use our analytics implementation on their own.

First, we import this hook from the SDK library:

// Import useAnalyticsEvent as a named export from flagship-sdk
import {useAnalyticsEvent} from '@brandingbrand/flagship-sdk';

Then we invoke the hook.

Note: Because this is a hook it must always be invoked within the body of a Functional Component!

const {trackEvent, trackConversionEvent} = 
useAnalyticsEvent();

You may notice there are two return values here, we will cover trackEvent in this section.

The payload as defined below can be whatever you want. Some props like postId, postTitle, and feedType will be sent with this event automatically. The props postId, postTitle, and feedType ARE reserved words for our implementation. If you attempt to add them here we will remove them.

The event here is of type onClick as such it will show in the dashboard as this type of event.

<TouchableOpacity
    //Wherever you need to use this event call it
    onPress={() =>
        trackEvent({
            myCustomProps: 'Analytics Portal',
        })
    }>

Below is a full example of what a portal with a custom event might look like:

import {Text, TouchableOpacity, View} from 'react-native';
// Import useAnalyticsEvent as a named export from flagship-sdk
import {useAnalyticsEvent} from '@brandingbrand/flagship-sdk';

// Portals are just react functional components defined in the client app
export const AnalyticsPortal = () => {
    const {trackEvent} = useAnalyticsEvent();

    return (
        <View>
            <TouchableOpacity
                onPress={() =>
                    trackEvent({
                        myCustomProps: 'Analytics Portal',
                    })
                }>
                <Text>Click or Press Me!</Text>
            </TouchableOpacity>
        </View>
    );
};

Conversion Tracking

Conversion tracking has been made to work outside a feeds portal.

Getting access to this method will be available when the client (end user app) instantiates the SDK.

The "trackConversion" method is exposed below.

import Flagship from '@brandingbrand/flagship-sdk';

const { FlagshipFeed, FlagshipStory, FlagshipService, trackConversion } = Flagship({
    appId: 'YOUR_APP_ID',
    // Optional - provide your event handlers. You can provide these as props
    // to the FlagshipFeed or FlagshipStory components if you'd like
    // to have different handlers for each Feed or Story.
    handleShowStory: YOUR_SHOW_STORY_HANDLER,
    handleCloseStory: YOUR_CLOSE_STORY_HANDLER,
    handleDeepLink: YOUR_DEEPLINK_HANDLER,
    handleAnalytics: YOUR_ANALYTICS_HANDLER,
    handleError: YOUR_ERROR_HANDLER
});

The payload for this is similar to the last example. However, you may notice the custom payload is now the second argument!

This is because the first argument of Revenue IS NOT optional.

The value corresponding to the revenue key in the request body is expected to be a JSON object with currency and amount. currency is a ISO 4217 string representing the currency code, e.g. "USD" or "EUR". amount should be string "1322.22".

JavaScript floats are too imprecise to rely on.

We strongly suggest converting your floats as shown below, floats will be rejected!

Below is an example of how you may use the method:

<TouchableOpacity
    onPress={() => {
        trackConversion({amount: 22.33.toPrecision(4), currency: 'USD'})
    }}>
    <Text>Confirm Purchase</Text>
</TouchableOpacity>

Integrating Analytics

Overview

We recommend implementing the analytics event handler so that you can track users' interactions with your content and measure the app's performance.

A common integration is with Google Analytics via Firebase. Below is an example of how you can easily set this up:

Google Analytics via Firebase Setup

Android

import com.google.firebase.analytics.FirebaseAnalytics

fun handleAnalytics(
    postID: String?,
    title: String?,
    action: String?,
    url: String?,
    eventID: String?
) {
    val analytics = FirebaseAnalytics.getInstance(context)
    val parameters = Bundle()
    parameters.putString(FirebaseAnalytics.Param.CONTENT_TYPE, "flagship")
    parameters.putString(FirebaseAnalytics.Param.ITEM_ID, eventID ?: postID)
    parameters.putString(FirebaseAnalytics.Param.TITLE, title ?: "")
    analytics.logEvent(FirebaseAnalytics.Event.SELECT_CONTENT, parameters)
}

iOS

import FirebaseCore

func handleAnalytics(
    postID: String?,
    title: String?,
    action: String?,
    url: String?,
    eventID: String?
) {
    Analytics.logEvent(AnalyticsEventSelectContent, parameters: [
        AnalyticsParameterItemID: eventID ?? postID,
        AnalyticsParameterItemName: title ?? "",
        AnalyticsParameterContentType: "flagship",
    ])
}

React Native

import analytics from '@react-native-firebase/analytics';

function handleAnalytics(
    postID: string,
    title: string,
    action: string,
    url: string,
    eventID: string
) {
    analytics.logSelectContent({
        content_type: 'flagship',
        // Send the user-defined custom event ID or fallback to the post ID
        // if not provided
        item_id: eventID || postID
    });
}

Did this answer your question?