@brandingbrand/fsengage
    TypeScript icon, indicating that this package has built-in type declarations

    11.1.0 • Public • Published

    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

    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

    Keywords

    none

    Install

    npm i @brandingbrand/fsengage

    DownloadsWeekly Downloads

    3,673

    Version

    11.1.0

    License

    MIT

    Unpacked Size

    435 kB

    Total Files

    162

    Last publish

    Collaborators

    • prashanth_kaduluri
    • akilar
    • brenont
    • manu-grondona
    • aarontjdev
    • philtompkins
    • ray.wu
    • mjmangus16
    • its.hui3
    • maksymdeminbbc
    • amandaphail-bb
    • jon.ploucha
    • markwissler
    • nathan-sankbeil
    • henry.saintjuste
    • clapton
    • swhite2
    • coughdrop
    • raghunandanp
    • roanblanchard
    • angelotrif
    • chrisjlan89branding
    • branderbrett
    • skyeckstrom
    • nickburkhartbb
    • bbtravis
    • laineh
    • deemaabdallah
    • chukohsin
    • msiauko
    • evan.katz
    • tuckerbrander
    • davidwachlin.bb
    • jasonmosleybb
    • dshadrick
    • nickbb
    • notajvento
    • andyschwob
    • brad.habenicht
    • rosahbruno
    • xero
    • mike.lux
    • caleb.griffith
    • tim.matyas
    • olksns
    • varzamanbb
    • bb_jenkins
    • crherman7
    • anna.larionova
    • olexandor
    • bodrus
    • cboetto
    • huizhuz
    • danrudolf2
    • celuchnb
    • abhishek_npm
    • lhenze33
    • romaniukua
    • tboetto
    • erichfeinstein
    • sjotterman
    • zrispo
    • omarkoueifi
    • danish.khalid
    • devs9-core
    • alex-black112
    • nasliedkov
    • wsedlacekc
    • john-marcello
    • dman01989
    • bhushan.kini
    • vyy7gn8j297flmyqgsmb
    • beaukenny
    • edelgado20
    • brandonacb
    • seanirby
    • sauceknight
    • ckornell
    • jmwr
    • mjweb48
    • winescout
    • southpeter
    • gametack
    • bryan-boeing
    • dmitriy_pchela
    • thepinkhatdev
    • a4heng
    • bbksmith
    • ashleygerst
    • gregwinn
    • clockelliptic
    • nevidomskii
    • jcsison
    • freesco16
    • jamesgraham2595
    • scbb31994
    • andrey_ionel
    • christianlovern
    • elad.karni