@gitlab/application-sdk-js

GitLab Application SDK - JS Core

This SDK is for usage of GitLab Application Services with vanilla Javascript.

Development guidelines

• yarn build builds the npm packages and the classic browser library
• yarn test builds the packages and runs jest tests
• yarn clean cleans the dist folder
• yarn lerna:publish to publish a newly built package. You need to run npm login with your personal npm login before.

How to call the script

Using the NPM package

Add the NPM package to your package JSON using your preferred package manager:

yarn add @gitlab/application-sdk-js

--

npm i @gitlab/application-sdk-js

Then for browser usage you can import the client SDK:

import { glClientSDK } from '@gitlab/application-sdk-js';

this.glClient = glClientSDK({ appId, host });

Or for Node.js you can require the client SDK instead (if ES modules are not supported):

const { glClientSDK } = require('@gitlab/application-sdk-js');

this.glClient = glClientSDK({ appId, host });

Using the script directly

Add the script to the page and assign the client SDK to window:

<script src="https://unpkg.com/@gitlab/application-sdk-js/dist/gl-sdk.min.js"></script>
<script>window.glClient = window.glSDK.glClientSDK({
    appId: 'YOUR_APP_ID',
    host: 'YOUR_HOST',
});</script>

Note: You can use specific version with like this,

    <script src="https://unpkg.com/@gitlab/application-sdk-js@0.0.5/dist/gl-sdk.min.js"></script>

Script initialization options

Option	Description
appId	This is the ID given by the GitLab Project Analytics setup guide. This is used to make sure your data is sent to your analytics instance.
host	This is the GitLab Project Analytics instance that is given by the setup guide.
hasCookieConsent	To use cookies to identify unique users and record their full IP address, set to true. This is set to false by default. When false, unique users are identified using fingerprinting instead of cookies and only records the first three octets of the IP address. Fingerprinting is sufficient enough to identify most unique users whilst maintaining some privacy. Learn more.
respectGlobalPrivacyControl	To respect the user's GPC configuration to permit or refuse tracking. This is set to true by default. When false, events will be emitted regardless of user configuration.

Methods

identify

Used to associate a user and their attributes with the session and tracking events.

glClient.identify(userId, userAttributes)

Property	Type	Description
userId	String	The user identifier your application users to identify individual users.
userAttributes	Object/Null/undefined	The user attributes that need to be added to the session and tracking events.

page

Used to trigger a pageview event.

glClient.page(eventAttributes)

Property	Type	Description
eventAttributes	Object/Null/undefined	The event attributes that need to be added to the pageview event.

track

Used to trigger a custom event.

glClient.track(eventName, eventAttributes)

Property	Type	Description
eventName	String	The name of the event.
eventAttributes	Object/Null/undefined	The event attributes that need to be added to the tracked event.

Developing with the devkit

To develop with a local Snowplow pipeline you can use the Analytics devkit's snowplow setup.

Setup the devkit

1. Run curl -X POST http://localhost:4567/setup-project/example -u [username]:[password] to set up Clickhouse for receiving events from the GDK. Use the credentials for the analytics-configurator.
2. Note down the app_id that is returned from the configurator.
3. Modify examples/vanilla-js/src/index.js to point at your local devkit and project

const SNOWPLOW_COLLECTOR_URL = 'localhost:9091';
const APPLICATION_ID = '[app_id  from configurator]';

1. If you haven't yet, build the SDK with yarn build at the root of gl-application-sdk-js.
2. Run the example by running yarn serve within examples/vanilla-js
3. Go to http://localhost:8080 to press the buttons on the example page

Seeing the events in Clickhouse

1. Go to http://localhost:8123/play and use the credentials for Clickhouse.
2. Then run your GDK e.g. with gdk start
3. Click around in your local GitLab version
4. Run SELECT * from example.snowplow_events Order by collector_tstamp desc to see the incoming events