Skip to main content

Integration Guide

Definition​

This document outlines the step-by-step instructions on how to utilize miniapp SDK wrapper for miniapp analytics tracker and for typescript.

What is a wrapper​

An Pule miniapp SDK wrapper is a technology-specific minimalistic SDK, that exposes the bare minimum functionality needed by the Pulse miniapp SDK, hiding all the complexity and loading details from the client, and provides easy-to-use APIs to get the requested configuration, more on the relation between the wrappers and SDKs, and the architecture can be found here.

Wrappers​

Artifact access configuration for local environments​

  1. Make sure you have Reporter role in gitlab for pulse-web project
  2. Add these lines to your .npmrc file
@pulse:registry=https://gitlab.com/api/v4/projects/23778878/packages/npm/

always-auth=true

Artifact access configuration for CI pipelines​

  1. Ask the CET team to whitelist your project by utilizing the public channel.

@Pulse/mini​

Installation​

npm i –save @pulse/mini

Initialization​

The wrapper efficiently loads the necessary scripts and bundles based on the configurations requested by the client during initialization. If preloading has already occurred, this step will be skipped.

import { initializeBrowserPulseMini } from "@pulse/mini";

initializeBrowserPulseMini({
  config: {
    tracker: {},
  },
  attributes: {
    appName: "root application name",
    miniAppName: "mini application name",
    miniAppVersion: "mini application version",
    miniAppId: "mini application ID",
  },
  transport: (message: any) => void,
  route: IModel<T, G>,
});
note

A navigation event will fire if the route streams a new value and the URL will be composed based on the provided properties.

IModel​

interface IModel<T, G extends IModelConfiguration = IModelConfiguration> {
    getState: () => T;
    setOptions: (options: G) => void;
    dispatch: (value: T, options?: IModelConfiguration) => void | Promise<void>;
    subscribe: (callback: (nextValue: T) => void, options?: ISubscriptionOptions) => () => void;
}

Input​

attributes: Attributes are key-value pairs with the following required properties:

  • appName: "root application name"
  • miniAppName: "mini application name"
  • miniAppVersion: "mini application version"
  • miniAppId: "mini application ID"

Additionally, the client can provide extra attributes that will be included in each event.

transport: The client needs to provide a transport function responsible for delivering events to the Pulse SDK, based in the root application.

config: The configuration object consists of keys representing the names of the SDK component and it's corresponding configuration options. Presented below is the schema for the configuration object of the Tracker miniapp SDK:

export abstract class TrackerConfigurations {
    debug: string[];
}

Tracker SDK​

The pulse miniapp tracker sdk object will contain nothing at the moment of writing this doc, once the tracker sdk is requested from the wrapper (by adding ‘tracker’ to the sdks array in the initialization), developers can use the dataLayer public array to publish events as follows:

dataLayer.push(
  {
    pulse: "state",
    user_id: 7733339543522,
  },
  {
    pulse: "event",
    event: "upload_done",
    parameters: { size: 12000 },
  }
);

And if the tracker isn’t fully loaded at the moment of publish, it will pick up all the queued events inside the dataLayer once it is, so no events will be lost.

Events verification​

To make sure you have successfully integrated the Pulse miniapp SDK and your events get fired as expected, visit the tools debugger (choose the appropriate application and move to the debugger page) and enable the debug mode in your root application by executing the following command in your browser console, or turn on debug mode if you use mobile platform:

pulse.tracker.queue.batchQueue.transport.debug.enable("debugger");

If your application is running inside an iFrame hosted on other pages, make sure to run the command in the context of the iFrame where the sdk is integrated.