@sb1/sb1-adobe-analytics

v4.2.1

Published

3 years ago

An SDK for working with analytics at SpareBank1

Downloads

0High
0Medium
0Low

Adobe Analytics SDK

An SDK for using Adobe Analytics in single-page applications (SPA) and other web applications at SpareBank 1. The current implementation supports only Adobe Analytics at the moment, but when using the API, the backend analyse tool is kind of hidden. So if the backend tool should be switched, the API should be kept the same.

The SDK (npm library) offers functions that can be used by the SPA to track:

pages that users visit
buttons/links/menus that are clicked
schemas/forms with multiple steps, e.g. a loan application where you want to track conversion rate
etc.

The SDK acts as a wrapper to the Adobe Launch script (see 1. Adobe Analytics Setup below). I.e. a function in the SDK is normally mapped to a corresponding function in the Launch script, so this requires that the Launch script is loaded when the SDK functions are used.

E.g. the trackButtonClick('buttonName) in the SDK, will be forwarded to _satellite.track('buttonClick'). buttonName will be added to the DOM object digitalData. The satellite track function will use data from this object when sending the request to the remote Adobe server. This will be a HTTP Post with analyse data contained as request parameters. Note that tracking has a price cost for SpareBank 1, so we should not track each and everything that happens in the app.

The Adobe Launch script is a dynamic script that is configurable using the Adobe Launch online tool. It is possible to define in the tool what shall happen when e.g. the _satellite.track('buttonClick') is called, and how e.g. the buttonName is mapped to a corresponding Adobe eVar, and buttonClick to a corresponding Adobe event. The mapping from different tracking variables to eVar/events are common for all SB1 apps, and adding more of them also has a cost. Therefore coordination and usage of Adobe Launch tool and eVar mapping is done by the Nettsider team in SB1.

The dynamic behaviour of the Launch script is the reason why it is included in the html document in head (see below) and not as an npm package. The Launch script is downloaded every 30min from Adobe and hosted on a SpareBank 1 server. The SB1 apps will request the script from the SB1 server and not directly from Adobe.

1. Adobe Analytics Setup

To get analytics working in your application, you must include the Adobe Launch script in your document <head>.

<script type="text/javascript" src="https://www.sparebank1.no/var/cq/dtm-reactor/clientlibs/EN62f569560777430297ad200bd5fb63ea/launch-EN62f569560777430297ad200bd5fb63ea.min.js"></script>

Additionally, the following must be placed at the end of the <body> tag:

<script type="text/javascript">_satellite.pageBottom();</script>

The pageBottom tells the Adobe satellite object that a page load has finished. To see verbose output from analytics, you can enter _satellite.setDebug(true) in your console, and you should see logging of all element clicks, direct call tracks, etc. In order to see calls that are sent to Analytics, it is possible to install the Chrome extension 'Omnibug'. This shows up as a tab in Developer tools in Chrome. In the Network tab, the analytics calls can also be identified with name starting on s. E.g. s89931057581221. However the Omnibug presentation is more readable.

2. Installation

Using the SDK requires that the Adobe Analytics script (Launch script above) is loaded in your application. The SDK is a npmjs.org hosted npm package:

npm i -S sb1-adobe-analytics

You can then import it in your code:

import * as analytics from 'sb1-adobe-analytics';

Or go vintage with this 1995 script tag!

If you don't use a bundler, you can also include a prebuilt minified version that exposes all methods through the global variable sb1analytics. Include it like so:

<script src="path/to/node_modules/sb1-adobe-analytics/dist/adobe-analytics.min.js"></script>

3. Initialization (mandatory)

An init function is exported that is used to initialize the SDK and the data layer.

NB ! The init function is mandatory

It takes an object with the following keys as its only argument:

Arguments

config (Object): An object with the following keys:
- businessUnit (string, required): The SB1 business unit that owns the application (e.g., SpareBank 1, SpareBank 1 Forsikring).
- subBrand (string, required): This is set to the user's bank (domain name) or forsikring (e.g. ostlandet, smn, sr-bank, forsikring)
- language (string, required): The current language e.g. 'nb', 'en' or 'nn'
- application (string, required): The name of the application (e.g., pm-blikunde, pm-kort, mobilbank-pm).
- appType (string, optional): Used for AB testing. Set it to 'A' or 'B' if used.
- appVersion (string, optional): Application version.
- products (Array, optional): Which SB1 product the app belongs to. Implemented as an array in case the app should be related to more than one product.
  - name (string, required): SB1 product name. E.g. Boliglan for unge, Spare på konto, Husforsikring. Required if products is used.
  - category (string, required): SB1 category. E.g. Lån, Sparing, Forsikring. Required if products is used.
- disableUrlListener (boolean, optional): It is recommended to set this to true. This requires that the app calls the trackPageLoad function when a new page is loaded.
- disableUrlChangeTracking (boolean, optional): It is recommended to set this to true. This requires that the app calls the trackPageLoad function when a new page is loaded.
- disableDeclaredId (boolean, optional): Default set to false since it is used in all SB1 apps. If Declared Id is not used (Adobe Audience Manager, tracking between devices), set it to true.
- domainPrefix (string, optional): Used as prefix in pageName in analytics, so change it with caution. Default is "sb1" if not set. Applicable if running in other domains than sparebank1.no.
- urlTransforms (Array, optional): An array of objects used to transform the URL in the case where the URL is not semantically descriptive. Used to generate more readable reports. Each object takes two keys:
  - pattern (string|RegExp, required): A pattern to search for in the URL
  - replace (string, required): The string to replace the matched patterns with.
- segment (object, optional): Which segment the user belongs to and status like e.g. login status.
  - orgID (string, optional): Organisation ID
  - orgIDemployees (string, optional): Organisation ID Employees
  - userid (string, optional): User id if applicable
  - userLoginstatus (string, optional): Login status e.g. authenticated_bankid, authorized

Example standard configuration

import { init } from 'sb1-adobe-analytics';

init({
  businessUnit: 'SpareBank 1',
  subBrand: 'smn',
  language: 'nb',
  application: 'finansieringsbevis',
  products: [
      {
          name: "Boliglan",
          category: "Lan"
      }
  ],
  disableUrlListener: true,
  disableUrlChangeTracking: true,
});

Example extended configuration

import { init } from 'sb1-adobe-analytics';

init({
  businessUnit: 'SpareBank 1',
  subBrand: 'sr-bank',
  language: 'nb',
  application: 'finansieringsbevis',
  appVersion: '1.0',
  products: [
      {
          name: "Boliglan",
          category: "Lan"
      }
  ],
  disableUrlListener: true,
  disableUrlChangeTracking: true,
  disableDeclaredId: false,
  domainPrefix: 'boligassistenten',
  urlTransforms: [
    {
      pattern: /accounts\/[A-Z0-9]+/,
      replace: 'accounts/account'
    },
    {
      pattern: /personal/,
      replace: 'mobilbank-privat'
    },
    {
      pattern: /insurances\/travel/,
      replace: 'travel-insurance'
    }
  ]
});

4. Track Page Load

trackPageLoad function shall be used each time a new page is loaded. It is recommended that the apps do this call themselves. Previously by setting disableUrlListener and disableUrlChangeTracking to false, there was some support of doing automatic pagetracking. However due to limitations in some versions of react router, it is recommended that the apps do this themselves. Note that function parameters pageName and location is usually not needed.

Note that trackPageLoad returns a Promise. If success, it will "resolve" with datalayer as parameter. If failure, it will "resolve" with null as parameter. It will not "reject" due to backward compatibility with apps that don't expect a Promise API.

Arguments

pageName (string, optional): Should only be set if the default page name found in the URL cannot be used.
location (object, optional): Should only be set if for some reason the window.location object needs to be overridden.

Example

import { trackPageLoad } from 'sb1-adobe-analytics';
trackPageLoad().then(function (datalayer) {
                if(datalayer) {//success} else {//failure} 
            });

5. Track Button Click

trackButtonClick function shall be used when a button, link or menu is clicked. Use short and descriptive text in the buttonText parameter, so that it is possibe to distinguish buttons on the same page. Note that the context, like which page/url this button is located, is not necessary to provide. This is due to that the context is already known (stored in digitalData object in DOM). Note that tracking has a price cost for SpareBank 1, so we should not track each and everything that happens in the app.

Note that trackButtonClick returns a Promise. If success, it will "resolve" with datalayer as parameter. If failure, it will "resolve" with null as parameter. It will not "reject" due to backward compatibility with apps that don't expect a Promise API.

Arguments

buttonText (string, required): Short descriptive text of the button/link/menu item etc that was clicked.

Example

import { trackButtonClick } from 'sb1-adobe-analytics';
trackButtonClick('Bestill kredittkort').then(function (datalayer) {
                                                       if(datalayer) {//success} else {//failure} 
                                                   });

6. Forms

The SDK has Form support. A form or schema typically consists of multiple steps where the user shall e.g. order something. The purpose of tracking forms, is partly to measure conversion rate, i.e. if the order ends up in a successfull sale or not. It is also possible to find out at which step users drop out, in order to discover design improvements.

6.1 Form initialisation

Remember to always call formInitiated on the object, in addition to the sdk init call.

new Form(formParams) It is necessary to create a Form object and then do function calls on this object.

formInitiated() function shall be called when a page that contains a form i loaded

Arguments

formParams (Object): An object with the following keys:
- formname (string, required): Name of form e.g. boliglan, bli kunde
- type (string, optional): Form context. Should normally be either bestill (if order/buy context) or kontakt (if contact context)
- formtype (string, optional): SB1 category like e.g. lan, spare, forsikre, bli kunde
- products (Array, optional): Should be set to which SB1 product the form relates to. E.g. boliglan, spare i fond, bilforsikring
  - name (string, required): Required if products is present in formParams. SB1 product. E.g. boliglan, spare i fond, bilforsikring
  - category (string, required): Required if products is present in formParams. SB1 category. Same as formtype, e.g. spare
- formUserType (string, optional): SB1 user type like lantaker, hovedlantaker or medlantaker. Use lantaker if there is no medlantaker.
- dualSign (string, optional): "true" or "false". Set to "true" if form can be signed by more than one person. E.g. boliglån with hovedlantaker and medlantaker.
- purpose (string, optional): Purpose of this form, e.g. kjøpe ny bolig
- appliedAmount (string, optional): Applicable in e.g. loan forms to indicate the applied amount
- approvedAmount (string, optional): Applicable in e.g. loan forms to indicate the approved amount by loan institution
- formVersion (string, optional): Form version (if applicable in addition to app version)
- transactionid (string, optional): Unique id for the specific form. E.g. can be used to correlate if user decides to continue later

Example

import { Form } from 'sb1-adobe-analytics';

const formParams = {
    formname: ‘finansieringsbevis’,
    type: ‘bestill’,
    formtype: ‘lan’,
    transactionId: '12345',
    products: [                 // Hvis form er relatert til et SB1 produkt, så brukes products
       {
          name: ‘boliglan for unge’,
          category: ‘lan’,
       }
    ],
};

let form = new Form(formParams);
form.formInitiated()

6.2. Form Update parameters

updateFormParams function shall be used to change existing form parameters or set new. Merge will be done, so not necessary to set form parameters that was set in constructor and that are not changed.

Arguments

updatedFormParams (object, required): See possible formParams in constructor above

Example

form.updateFormParams({
    formUserType: 'medlantaker',
    dualSign: 'true',
    purpose: 'kjøpe ny bolig',
    appliedAmount: '500',
    approvedAmount: '400'})

6.3. Form Step Started

formStepStarted function shall be used when user starts to fill in data in the form. It shall only be called once for the current step/page. If the form contains multiple steps, formStepStarted shall be called once for each step. Note that formInitiated above shall only be called once when a page containing a form is loaded, and only before first formStepStarted. If user navigates back and forth, ideally formStepStarted shall not be called again. If the form contains a "receipts/kvitteringsside" at the end, formStepStarted with formStepName/No shall also be called.

Arguments

formStepName (string, required): Name of current step. Use a simple logical name
formStepNo (string, required): Increasing step number (1, 2, 3 etc). If form has multiple paths, let each step have a unique number. I.e. you can have step numbers with sequence 1,2,5,6,7 etc for a given path.
formUserType (string, optional): SB1 user type like lantaker, hovedlantaker or medlantaker. Use lantaker if there is no medlantaker.
products (object, optional): products object. See formParams in constructor above

Example

form.formStepStarted({
	formStepName: ‘okonomi’,
	formStepNo: ‘1'})

6.4. Form Completed

formcompleted function shall be called when user has finished the form, and after the last formStepStarted. E.g. when user press finish/ok in last step. If the form is dependent on backend systems, it should wait for this response before sending formCompleted.

Arguments

submitStatus (string, required): Valid submitStatus are: 'success', 'partial success', 'denied', 'manual', 'user cancel', 'continue later', 'error' or 'not known'
transactionId (string, optional): See formParams in constructor above
products (string, optional): See formParams in constructor above

Explanation of submitStatus:

success: used if things went ok. i.e. the user applied for a loan etc
partial success: used e.g. in a loan where two people have to fill in forms, and the first person applies successfully
denied: used e.g. if loan application was denied due to missing credit
manual: used e.g. if the application needs special intervention by a human being before any response can be given.
user cancel: used e.g. if the user cancel the form
continue later: used e.g. if the form is temporarily stopped by the user and will be continued later. e.g. Huskeliste.
error: used e.g. if some kind of error message is retrieved from backend system

Example

form.formCompleted({submitStatus: 'success'});

6.5. Form Error

formErrors function can be called if one or more fields in the current formstep has validation errors

Arguments

errors (Object): An object with the following keys:
- fieldName1 (string, required): Description of error in this field
- fieldName2 (string, required): Description of error in this field
- fieldName3 (string, required): Description of error in this field etc

Example

form.formErrors({mail: ‘ikke gyldig mail addresse’,
                 navn: ‘ikke gyldig navn’})

7. Chatbot

The SDK has support for chatbot tracking. It supports tracking of:

user initiate a chat with the chatbot
user initate a chat with an SB1 advisor
user clicks on an internal link (SB1)
user clicks on an external link (outside SB1)

7.1 Start chat with chatbot

trackChatBotStart function shall be used when user initiate a chat with the chatbot (e.g. clicks a button)

Note that trackChatBotStart returns a Promise. If success, it will "resolve" with datalayer as parameter. If failure, it will "resolve" with null as parameter. It will not "reject" due to backward compatibility with apps that don't expect a Promise API.

Arguments

Example

import { trackChatBotStart } from 'sb1-adobe-analytics';
trackChatBotStart().then(function (datalayer) {
                if(datalayer) {//success} else {//failure} 
            });

7.2 Start chat with an SB1 Advisor

trackChatOperatorStart function shall be used when user initiate a chat with an advisor in the bank (e.g. clicks a button)

Note that trackChatOperatorStart returns a Promise. If success, it will "resolve" with datalayer as parameter. If failure, it will "resolve" with null as parameter. It will not "reject" due to backward compatibility with apps that don't expect a Promise API.

Arguments

Example

import { trackChatOperatorStart } from 'sb1-adobe-analytics';
trackChatOperatorStart().then(function (datalayer) {
                if(datalayer) {//success} else {//failure} 
            });

7.3 Clicks on an external link (outside SB1) in the chat

trackChatExternalLink function shall be used when user clicks on an external link that is provided by the chatbot or the Advisor (chatoperator)

Note that trackChatExternalLink returns a Promise. If success, it will "resolve" with datalayer as parameter. If failure, it will "resolve" with null as parameter. It will not "reject" due to backward compatibility with apps that don't expect a Promise API.

Arguments

fullURL (string, required): Full URL of e.g. the link that was clicked on in the chat
type (string, required): Type of chat. Should be chatbot or chatoperator (advisor)

Example

import { trackChatExternalLink } from 'sb1-adobe-analytics';
trackChatExternalLink({fullURL, type}).then(function (datalayer) {
                if(datalayer) {//success} else {//failure} 
            });

7.4 Clicks on an internal link (SB1) in the chat

trackChatInternalLink function shall be used when user clicks on an internal link that is provided by the chatbot or the Advisor (chatoperator)

Note that trackChatInternalLink returns a Promise. If success, it will "resolve" with datalayer as parameter. If failure, it will "resolve" with null as parameter. It will not "reject" due to backward compatibility with apps that don't expect a Promise API.

Arguments

fullURL (string, required): Full URL of e.g. the link that was clicked on in the chat
type (string, required): Type of chat. Should be chatbot or chatoperator (advisor)

Example

import { trackChatInternalLink } from 'sb1-adobe-analytics';
trackChatInternalLink({fullURL, type}).then(function (datalayer) {
                if(datalayer) {//success} else {//failure} 
            });

7.5 Clicks on a link in the chat

trackChatLink function shall be used when user clicks on a link that is provided by the chatbot or the Advisor (chatoperator)

Note that trackChatLink returns a Promise. If success, it will "resolve" with datalayer as parameter. If failure, it will "resolve" with null as parameter. It will not "reject" due to backward compatibility with apps that don't expect a Promise API.

Arguments

fullURL (string, required): Full URL of e.g. the link that was clicked on in the chat
type (string, required): Type of chat. Should be chatbot or chatoperator (advisor)
overrideSB1UrlPattern (object, optional): RegExp. Possible to override what will match an SB1 address. Based on match or not, it will call trackChatInternalLink or trackChatExternalLink respectively.

Example

import { trackChatLink } from 'sb1-adobe-analytics';
trackChatLink({fullURL, type, overrideSB1UrlPattern}).then(function (datalayer) {
                if(datalayer) {//success} else {//failure} 
            });

8. API Reference

See src/index.js to see all exported functions. All exported functions are annotated with JSDoc annotations about usage. Functions also have JSDoc, so it is possible to find more details in each javascript.

9 Contribute in development

Have a look in CONTRIBUTING.md on how to take part in development of the SDK.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Adobe Analytics SDK

1. Adobe Analytics Setup

2. Installation

Or go vintage with this 1995 script tag!

3. Initialization (mandatory)

NB ! The init function is mandatory

Arguments

Example standard configuration

Example extended configuration

4. Track Page Load

Arguments

Example

5. Track Button Click

Arguments

Example

6. Forms

6.1 Form initialisation

Arguments

Example

6.2. Form Update parameters

Arguments

Example

6.3. Form Step Started

Arguments

Example

6.4. Form Completed

Arguments

Example

6.5. Form Error

Arguments

Example

7. Chatbot

7.1 Start chat with chatbot

Arguments

Example

7.2 Start chat with an SB1 Advisor

Arguments

Example

7.3 Clicks on an external link (outside SB1) in the chat

Arguments

Example

7.4 Clicks on an internal link (SB1) in the chat

Arguments

Example

7.5 Clicks on a link in the chat

Arguments

Example

8. API Reference

9 Contribute in development