faster-sdk-js

Faster Analytics SDK - JavaScript

Faster is a framework which provides analytics, account, billing and remote-config features. This project is related to SDK for Javascript development given a easy-to-use API to work with.

Currently released features:

• Analytics (This package):

  • Track Device Installation
  • Session Control
  • Track & Send Events

• Remote Config (Check Package):

  • Run AB Tests
  • Manage Feature Rollout

• Account (Check Package):

  • Manage Sessions
  • Create, Link and Manage Credentials

• Billing: coming soon

1 - Getting Started

Installing

Get the package from the public npm registry, with your favorite package manager:

yarn add faster-sdk-js

or

npm install faster-sdk-js

Request credentials

Request a new applicationKey and applicationSecret with faster-team at Movile.

For security purpose DO NOT share or store your applicationSecret.

Usage

Import the Faster module and FasterConfiguration object using ES6 syntax.

import Faster, { FasterConfiguration } from 'faster-sdk-js';

Configuring & Running

Now, configure and start Faster SDK:

const configuration = new FasterConfiguration('__appKey__', '__secretKey__', options);
Faster.configure(configuration);
const fasterAnalyticsInstance = Faster.start();

Event Builder

Event builder used to create proper Faster Event instances.

import { EventBuilder } from 'faster-sdk-js';

const eventBuilder = new EventBuilder(eventId, eventRevision);
const event = eventBuilder
  .id('some-event-id')
  .externalId('another_tracking_tool_id')
  .dimension('someStringProperty', 'someValue')
  .dimension('someBooleanProperty', true)
  .dimension('someNumberProperty', 300)
  .build();

Then you can register the event in Faster Analytics:

fasterAnalyticsInstance.event.register(event);

2 - API Reference

Faster Analytics

FasterConfiguration.constructor(applicationKey, secretKey, appVersion, [options])

• applicationKey: The application key created for your application in the Faster Admin system.
• secretKey: The application secret key created for your application in the Faster Admin system.
• options: Optional parameters to configure the Faster modules:
  • appVersion: Your application version string, used for tracking.
  • timeout: Request timeout in miliseconds for all Faster operations.
  • sessionTtl: Faster Session maximum lifetime in seconds.
  • sessionProperties: properties to add in every new session. This does not change the session properties if the session has already started. This merges with properties from expired sessions, but in case of conflicts, the expired session properties wins over. See Faster.session.putProperties for other use cases

Faster.configure(configuration):

• configuration : FasterConfiguration instance.

Faster.start([trackInstall]):

Most common startup way for faster

• trackInstall: Indicates whether or not a new install event should be registered when creating the device information.

Faster.startEmbedded(externalDeviceId, externalSessionId):

For applications embedded inside other applications that use Faster. In this mode, only event tracking will be available, as Device and Session information are handled by the parent application.

• externalDeviceId: External application Faster Device ID.
• externalSessionId: External application Faster Session ID.

ServerDate

It provides a date that is synchronized with the server time. This is really useful when you want to keep track of a timeline of facts.

now(): Date:

Calculates what would be the given moment taking into consideration the time difference with the server.

If the time difference is bellow 4 seconds, only the client time is considered. If the time from the serve is not yet retrieved it returns null instead.

Example of usage:

import FasterAnalytics, { ServerDate } from 'faster-sdk-js'

FasterAnalytics.configure(fstrConfig);
const fasterAnalytics = FasterAnalytics.start();

console.log(ServerDate.now())

Faster.device.get():

Returns the entire Device object with all information collected by Faster.

Faster.device.putProperty(name, value):

Inserts a new custom property in the device information.

• name: The property identification name.
• value: The property value, must be boolean, number or string.

Faster.device.putProperties(properties):

Inserts a new set of custom properties in the device information.

• properties: Object with new properties. The values must be boolean, number or string.

Faster.device.removeProperty(name):

Removes a property with the given name from properties in the device information.

• name: Property identification name.

Faster.device.updatePushToken(pushSubscription):

Updates the push identifier of the client in the device information.

• pushSubscription: PushSubscription object from PushAPI.

Faster.session.get():

Returns the entire Session object with all information collected by Faster.

Faster.session.putProperty(name, value):

Inserts a new custom property in the Session information.

• name: The property identification name.
• value: The property value, must be boolean, number or string.

Faster.session.putProperties(properties):

Inserts a new set of custom properties in the Session information.

• properties: Object with new properties. The values must be boolean, number or string.

Faster.session.removeProperty(name):

Removes a property with the given name from properties in the Session information.

• name: Property identification name.

Faster.session.updateUserId(userId):

Updates the user id of the client in the Session information.

• userId: String with the user id.

Faster.session.updateGeoPoint(geopoint):

Updates the geopoint of the client in the Session information, if the client moves more than approximately 100m.

• geoPoint: Property composed by latitude and longitude.

import { GeoPoint } from 'faster-sdk-js'

new GeoPoint(100, 100)

Faster.event.register(event):

Registers a new event in the Faster database. This method provides request count control and retry mechanisms.

• event: A Faster Event object, can be instanced using the event builder packed with the SDK.

Faster.event.registerWithPromise(event):

Registers a new event in the Faster database, returning a promise of the process. This method does not provide retry and request count control.

• event: A Faster Event object, can be instanced using the event builder packed with the SDK.

EventBuilder

EventBuilder.constructor(eventType, eventRevision):

• eventType: Event type string identifier from Faster Admin system.
• eventRevision: Event type revision number from Faster Admin system.

EventBuilder.id(id):

Set the id value used by Faster for the built event.

• id: String identification value.

EventBuilder.externalId(id):

Set the id value from external sources for the built event.

• id: String identification value.

EventBuilder.dimension(key, value):

Add a new custom property to the built event.

• key: Property identification string key.
• value: Property value, must be boolean, number or string.

EventBuilder.dimensions(dimensions):

Add multiple custom properties to the built event.

• dimensions: Object containing properties to be added, values must be boolean, number or string.