@brandingbrand/fsengage

FSEngage

FSEngage is Flagship's Engagement package. It Analytics library supports integrations for Google Analytics, Leanplum, and Adobe Cloud Marketing. Its CMS library supports our proprietary CMS and soon will support Demandware.

• Analytics
  • Analytics Providers
  • Analytics Providers Configuration
    • Analytics Provider Configuration
    • Leanplum
    • Adobe Marketing Congfiguration
    • Google Analytics
  • Analytics Constructors
  • Analytics Tracking
    • Ecommerce Function Signatures
    • Enhanced Ecommerce Function Signatures
    • App Lifecycle Function Signatures
    • Full List of Property Parameters for Tracking
    • Sending Custom Fields to Google Analytics
• CMS
  • CMS Providers
    • Core
    • Demandware
  • CMS API
    • CMS Configurations
    • CMS Constructors
    • Functionality
• Tests

Analytics

The analytics library includes convenient integrations for Google Analytics, Leanplum, and Adobe Marketing cloud. Getting started with our analytics library is as easy as configuring your analytics providers and passing these configs into the Analytics constructor. Then you will be able to import your analytics object into your app's components for easy tracking of ecommerce, enhanced ecommerce, and lifecycle events.

Analytics Providers

Leanplum

Leanplum is only supported in native environments.

Adobe Marketing Cloud

Adobe is only supported in native environments at the moment. The plan is to also provide support for web environment down the road.

Warning: Adobe native support has not been fully tested yet due to limited access to their platform at the time of development.

# iOS

In order to run Adobe native code wrapper, the below dependencies would need to be linked in the iOS project.

SystemConfiguration.framework
libsqlite3.0

Also, you will need to include in your bundle the configuration file ADBMobileConfig.json provided by Adobe Marketing Cloud.

For more information please go here.

API - Analytics

Analytics Configurations

Before generating your analytics object, you must first successfully configure your providers according to the following configuration signatures.

# AnalyticsProviderConfiguration

Property	Type	Required
userAgent	string	yes
osType	string	yes
osVersion	string	yes
appName	string	yes
appId	string	yes
appVersion	string	yes
appInstallerId	string	no

# AdobeMarketingCloudWebProviderConfiguration

Property	Type	Required
clientId	string	yes
clientSecret	string	yes
reportSuiteId	string	yes

Note: This configuration just applies for web environments. For native environment configuration please see here.

# GoogleAnalyticsProviderConfiguration

Property	Type	Required
trackerId	string	yes
clientId	string	yes
trackerName	string	no
cookieDomain	string	no

# LeanplumProviderConfiguration

Property	Type	Required
appId	string	yes
key	string	yes
monetizationEventName	string	no

Analytics Constructors

Once you have configured your providers, you will want to pass them to the Analytics constructor in order to output your own Analytics instance. Below you will find examples. The first user has chosen to Google Analytics alone, the second has chosen to use all three providers.

const AnalyticsProviderConfiguration = {
  userAgent: DeviceInfo.getUserAgent(),
  osType: Platform.OS,
  osVersion: (Platform.Version && Platform.Version.toString()) || '',
  appName: DeviceInfo.getApplicationName(),
  appId: DeviceInfo.getBundleId(),
  appVersion: version,
};

const googleAnalyticsConfiguration = {
  trackerId: projectEnv.googleAnalytics[Platform.OS],
  clientId: DeviceInfo.getUniqueID(),
};

const google = new GoogleAnalyticsProvider(
  AnalyticsProviderConfiguration,
  GoogleAnalyticsProviderConfiguration
);

const analytics = new Analytics([google]);

const adobe = new AdobeMarketingCloudProvider(
  AnalyticsProviderConfiguration,
  AdobeMarketingCloudWebProviderConfiguration
);
const google = new GoogleAnalyticsProvider(
  AnalyticsProviderConfiguration,
  GoogleAnalyticsProviderConfiguration
);
const leanplum = new LeanplumProvider(
  AnalyticsProviderConfiguration,
  LeanplumProviderConfiguration
);

const analytics = new Analytics([
  adobe,
  google,
  leanplum
]): Analytics;

Tracking Functions

Once you have successfully configured your Analytics provider, you can import it into your components and begin tracking users' interactions with your app or site. For example, on a Product Detail Page, you might want to add a click tracker to your 'Add To Cart' button. It's as simple as adding the following code to your success handler (assuming you only want to tracks successful adds):

Analytics.click.generic('Add to Bag', {
  identifier: variantId,
  name: 'PDP',
});

Or maybe you want to track a screenview of a product page. In that case you would want to add something like this into your render function:

Analytics.screenview('ProductDetail', {
  url: 'www.example.com/products/123',
});

The full list of function signatures for ecommerce, enhanced ecommerce, and lifecycle events can be found below. Following these are complete lists of all mandatory and optional properties for each function.

# Ecommerce

analytics.contact.call(component: React.Component | string, properties: ContactCall): void;

analytics.contact.email(component: React.Component | string, properties: ContactEmail): void;

analytics.click.generic(component: React.Component | string, properties: ClickGeneric): void;

analytics.location.directions(
  component: React.Component | string,
  properties: LocationDirections
): void;

analytics.search.generic(component: React.Component | string, properties: SearchGeneric): void;

analytics.impression.generic(
  component: React.Component | string,
  properties: ImpressionGeneric
): void;

analytics.screenview(component: React.Component | string, properties: Screenview): void;

# Enhanced Ecommerce

IMPORTANT: Enhanced hits are not sent on their own; instead, they piggy-back on standard hits such as impressions and screenviews. As such, you must invoke a screenview or similar hit after using any of the following methods in order for the data to be delivered.

analytics.impression.promotion(component: React.Component | string, properties: Promotion): void;

analytics.impression.product(
  component: React.Component | string,
  properties: ImpressionProduct
): void;

analytics.click.promotion(component: React.Component | string, properties: Promotion): void;

analytics.click.product(
  component: React.Component | string,
  properties: Product,
  action: ProductAction?
): void;

analytics.detail.product(
  component: React.Component | string,
  properties: Product,
  action: ProductAction?
): void;

analytics.add.product(component: React.Component | string, properties: Product): void;

analytics.remove.product(component: React.Component | string, properties: Product): void;

analytics.checkout(
  component: React.Component | string,
  products: Product[],
  action: CheckoutAction
): void;

analytics.checkoutOption(component: React.Component | string, action: CheckoutAction): void;

analytics.purchase(
  component: React.Component | string,
  products: Product[],
  action: TransactionAction
): void;

analytics.refund.partial(
  component: React.Component | string,
  products: RefundProduct[],
  action: TransactionAction
): void;

analytics.refund.all(component: React.Component | string, action: TransactionAction): void;

# App Lifecycles

analytics.lifecycle.active(): void;

analytics.lifecycle.background(): void;

analytics.lifecycle.close(): void;

analytics.lifecycle.create(): void;

analytics.lifecycle.inactive(): void;

analytics.lifecycle.start(): void;

analytics.lifecycle.suspend(): void;

Parameters

# ClickGeneric

Property	Type	Required
identifier	string	yes*
name	string	yes*
index	number	no
gaQueryParams	object	no

* Either identifier or name must be set.

# ContactCall

Property	Type	Required
number	string	yes
gaQueryParams	object	no

# ContactEmail

Property	Type	Required
to	string	yes
gaQueryParams	object	no

# ImpressionGeneric

Property	Type	Required
identifier	string	yes*
name	string	yes*
index	number	no
gaQueryParams	object	no

* Either identifier or name must be set.

# ImpressionProduct

Property	Type	Required
identifier	string	yes
name	string	yes
brand	string	no
category	string	no
list	string	no
variant	string	no
price	number	no
index	number	no
gaQueryParams	object	no

# LocationDirections

Property	Type	Required
identifier	string	yes*
address	string	yes*
gaQueryParams	object	no

* Either identifier or address must be set.

# Product

Property	Type	Required
identifier	string	yes
name	string	yes
brand	string	no
category	string	no
variant	string	no
coupons	string[]	no
price	string	no
quantity	number	no
index	number	no
gaQueryParams	object	no

# Promotion

Property	Type	Required
identifier	string	yes
name	string	yes
creative	string	no
slot	string	no
gaQueryParams	object	no

# RefundProduct

Property	Type	Required
identifier	string	yes
quantity	number	yes
price	string	no
coupons	string[]	no
gaQueryParams	object	no

# SearchGeneric

Property	Type	Required
term	string	yes
count	number	no
gaQueryParams	object	no

# Screenview

Property	Type	Required
url	string	yes
gaQueryParams	object	no

Actions

# ProductAction

Property	Type	Required
list	string	no
gaQueryParams	object	no

# CheckoutAction

Property	Type	Required
step	number	no
option	string	no
gaQueryParams	object	no

# TransactionAction

Property	Type	Required
identifier	string	yes
affiliation	string	no
revenue	string	no
tax	string	no
shippingCost	string	no
coupons	string[]	no
gaQueryParams	object	no

Sending Custom Fields to Google Analytics

The Google Analytics provider has support for specifying custom fields by way of setting gaQueryParams in the payload. A full list of officially supported GA fields can be found here.

Example usage:

analytics.impression.product({
  component: 'ProductComponent',
  properties: {
    identifier: 'abc123',
    name: 'Large Blue Pants',
    gaQueryParams: {
      tcc: 'SALE45',
    },
  },
});

CMS

CMS Providers

Core

Branding Brand's content management system is supported with some targets limitations at the moment. The targets currently supported are:

• City
• Country
• Date
• Postal Code
• Region
• State
• Time of Day
• Time Zone

Demandware

Demandware's content management system support is on the roadmap, but it is still on the exploration stage. A strategy for how to manage slots' content need to be set, since they are coming from the Data API, instead of the Shop API.

CMS API

CMS Configurations

# ContentManagementSystemProviderConfiguration

Property	Type	Required
propertyId	string	yes
environment	number	yes

CMS Constructors

const core = new CoreContentManagementSystemProvider(
  configuration: ContentManagementSystemProviderConfiguration
);
const cms = new ContentManagementSystem(provider: core);

Functionality

cms.shouldFallbackToGeoIP = true;

cms.shouldPromptForGelolocationPermission = true;

cms.contentForSlot(group: string, slot: string, identifier?: string): Promise<{}>;

Get a list of identifiers of the slot

cms.identifiersForSlot(group: string, slot: string): Promise<string[]>;

Tests

Native

In order to run native integrations tests, please execute the following commands:

1. npm install

2. npm run init

3. npm run ios || npm run android

Web

In order to run web integrations tests, please execute the following commands:

1. npm install

2. npm run init

3. npm run web