fuse-analytics-client

What is this repository for?

This is a analytics-client library which will be used to publish events to the FUSE Analytics Endpoint currently using Amplitude which will soon also support Keen Events.

It also does retry with an exponential delay between attempts - inspired from package

Installation

npm i @appfire/fuse-analytics-client

For amplitude config further steps are mentioned on https://appfireteam.atlassian.net/wiki/spaces/AC/pages/96025903789/Fuse+Amplitude+Analytics+Client+HTTP+Client+and+Improvements;

Usage

Sending Analytics from a Browser or from Backend

import { fuseAnalyticsClient } from '@appfire/fuse-analytics-client';


type CustomBody = {
  [key: string]: string | boolean | number | CustomBody;
  eventType: string //mandatory
};

// Pass the type of the Application i.e Monday/Confluence/Jira and create an analytics client
// the fingerPrintApiKey is specific to app which needs to be provided here
try {
  const analyticsClient = await fuseAnalyticsClient('Monday', {appKey: appKey, fingerPrintApiKey: <keySpecificToApp>});
  const event = {
    body: '______________ \\cos____ \\GREEKLETTER _ \\sin____ \\GREEKLETTER ',
    body_char_count: 61,
    action: 'Insert',
    editor_type: 'new',
    eventType: 'LmMacroConfigured',
    lm_feature: 'Block',
    page_id: 196695,
    macro_id: 'd1ad1d5eaafa1e87ecb9efb86120f313',
    space_id: '196612',
    device_id: 'DjhWrBHFhGvGjlGVqvZx',
    alignment: 'Left',
  };
  analyticsClient.sendAnalytics<CustomBody,string>(event);

} catch (error) {
  console.error('Final error', error);
}

Send Analytics Using Browser Beacon

If you need to be async and non-blocking for quicker response times, we can use the Beacon feature which can push the API call to a queue in the browser then this feature can be used more about this can be read here

Example

const response = await fuseAnalytics.sendAnalyticsBeacon<
  CustomEventType,
  boolean
>(JSON.parse(analyticsEvent));

Analytics Client

• appKey?: string This is appKey for Atlassian and appId for Monday Apps.
• fingerPrintApiKey?: string This is a key which is specific to application which needs to be given provided to load fingerprint API.
• sendAnalytics can be used to send the Events to Amplitude, and the event format can be defined here.

Using the backoff options while sending analytics

try {
  const atlassianService = fuseAnalyticsClient('Jira', {
    appKey: 'org.swift.confluence.emulation',
    serviceUrl: 'https://services.sand.bobswift.appfire.app/snapshot/utils/2.0/analytics',
    backOffOptions: {
      delayFirstAttempt: true,
      jitter: 'full',
      logRetry: true,
      numOfAttempts: 5,
      startingDelay: 100,
      timeMultiple: 5,
    },
    tokenFn: (async()=>{
      return (await mondaySdk().get("sessionToken")).data
    })
  });
  const response = await atlassianService.sendAnalytics<Body, string>({
    test: 'hahaha'
  })
  console.log({ data: response.data });
  console.log({ status: response.status });
} catch (error) {
  console.error('Final error', error);
}

Using Analytics Client as Open API

For using Analytics client as open Api.

1. Register to fuse app. Steps to register are mentioned on https://bitbucket.org/appfire/fuse-sdk/src/develop/libs/fuse-register/README.md
2. Use the appkey used to registed non fuse app in the client.

const openAPIAnalytics = async () => {
  const openApiAnalytics = fuseAnalyticsClient('Confluance', {
    appKey: appKey,
    serviceUrl: 'https://services.sand.bobswift.appfire.app/snapshot',
  });
    const event = {
      SaveProfile: true,
      anotherData: {
        test: 'test',
      },
      eventType: 'SaveProfile',
    };
    const response = await openApiAnalytics.sendAnalytics<
      CustomEventType,
      string
    >(JSON.parse(analyticsEvent));
};

BackOffOptions

• delayFirstAttempt?: boolean

  Decides whether the startingDelay should be applied before the first call. If false, the first call will occur without a delay.

  Default value is false.

• jitter?: JitterType | string

  Decides whether a jitter should be applied to the delay. Possible values are full and none.

  Default value is none.

• maxDelay?: number

  The maximum delay, in milliseconds, between two consecutive attempts.

  Default value is Infinity.

• numOfAttempts?: number

  The maximum number of times to attempt the function.

  Default value is 10.

  Minimum value is 1.

• retry?: (e: any, attemptNumber: number) => boolean | Promise<boolean>

  The retry function can be used to run logic after every failed attempt (e.g. logging a message, assessing the last error, etc.). It is called with the last error and the upcoming attempt number. Returning true will retry the function as long as the numOfAttempts has not been exceeded. Returning false will end the execution.

  Default value is a function that always returns true.

• startingDelay?: number

  The delay, in milliseconds, before executing the function for the first time.

  Default value is 100 ms.

• timeMultiple?: number

  The startingDelay is multiplied by the timeMultiple to increase the delay between reattempts.

  Default value is 2.

Token

The tokenFn is optional needs to return the users token, which will be used by the analytics client to send events to Amplitude/Keen when not present it will use the inbuilt mechanism.

A sample code to invoke analytics from lambda where we can read token from header or from request and pass it to analytics client.

tokenFn: the function which can return the token, only needed when the fuseAnalyticsClient is used in node environment

try {
  const atlassianService = fuseAnalyticsClient('Jira', {
    appKey: 'org.swift.confluence.emulation',
    serviceUrl: 'https://services.sand.bobswift.appfire.app/snapshot/utils/2.0/analytics',
    tokenFn: ()=>{ 
      return headers.get("authorization")
    }
  }); // it can be a function 
  const response = await atlassianService.sendAnalytics<Body, string>({
    test: 'hahaha'
  })
  console.log({ data: response.data });
  console.log({ status: response.status });
} catch (error) {
  console.error('Final error', error);
}