@brandingbrand/fsengage

Analytics, CMS, and Settings module for Flagship

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
@brandingbrand/fsengage
11.88.18 months ago6 years agoMinified + gzip package size for @brandingbrand/fsengage in KB

Popular Searches

Readme

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 Providers - Analytics Providers Configuration
- [Analytics Provider Configuration](#AnalyticsProviderConfiguration)
- [Leanplum](#LeanplumProviderConfiguration)
- [Adobe Marketing Congfiguration](#AdobeMarketingCloudWebProviderConfiguration)
- [Google Analytics](#GoogleAnalyticsProviderConfiguration)
- Analytics Constructors - Analytics Tracking
- [Ecommerce Function Signatures](#ecommerce)
- [Enhanced Ecommerce Function Signatures](#enhanced-ecommerce)
- [App Lifecycle Function Signatures](#app-lifecycle)
- [Full List of Property Parameters for Tracking](#parameters)
- [Sending Custom Fields to Google Analytics](#sending-custom-fields-to-google-analytics)
- CMS Providers
- [Core](#core)
- [Demandware](#demandware)
- CMS API
- [CMS Configurations](#cms-configurations)
- [CMS Constructors](#cms-constructors)
- [Functionality](#cms-constructors)

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