# @gitlab/application-sdk-js

> Client side JS SDK for GitLab Application services

Latest version **0.1.5** (published 2023-04-28) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @gitlab/application-sdk-js
pnpm add @gitlab/application-sdk-js
yarn add @gitlab/application-sdk-js
bun add @gitlab/application-sdk-js
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.1.5 |
| Published | 2023-04-28 |
| First published | 2022-08-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 6 |
| Unpacked size | 187.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | GitLab |
| Maintainers | apanchal-gitlab, rob.hunt-gitlab, gitlab-administration, tzallmann, gitlab-bot, leipert |
| Keywords | GitLab |

## Links

- npm: https://www.npmjs.com/package/@gitlab/application-sdk-js
- Repository: https://gitlab.com/gitlab-org/analytics-section/product-analytics/gl-application-sdk-js
- Homepage: https://gitlab.com/gitlab-org/analytics-section/product-analytics/gl-application-sdk-js#readme
- Issues: https://gitlab.com/gitlab-org/analytics-section/product-analytics/gl-application-sdk-js/issues
- npm.io page: https://npm.io/package/@gitlab/application-sdk-js

## Dependencies (6)

- [@snowplow/browser-tracker](https://npm.io/package/@snowplow/browser-tracker.md) ^3.9.0
- [@snowplow/browser-plugin-client-hints](https://npm.io/package/@snowplow/browser-plugin-client-hints.md) ^3.9.0
- [@snowplow/browser-plugin-form-tracking](https://npm.io/package/@snowplow/browser-plugin-form-tracking.md) ^3.9.0
- [@snowplow/browser-plugin-error-tracking](https://npm.io/package/@snowplow/browser-plugin-error-tracking.md) ^3.9.0
- [@snowplow/browser-plugin-performance-timing](https://npm.io/package/@snowplow/browser-plugin-performance-timing.md) ^3.9.0
- [@snowplow/browser-plugin-link-click-tracking](https://npm.io/package/@snowplow/browser-plugin-link-click-tracking.md) ^3.9.0

## Recent versions

- 0.1.5 (latest) — 2023-04-28
- 0.1.4 — 2023-04-28
- 0.1.3 — 2023-04-24
- 0.1.2 — 2023-04-20
- 0.1.1 — 2023-03-29
- 0.1.0 — 2023-03-29
- 0.0.5 — 2023-03-08
- 0.0.4 — 2022-09-29
- 0.0.3 — 2022-09-29
- 0.0.2 — 2022-09-29
- 0.0.1 — 2022-08-24

## README

# 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:

```shell
yarn add @gitlab/application-sdk-js

--

npm i @gitlab/application-sdk-js
```

Then for browser usage you can import the client SDK:

```javascript
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):

```javascript
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`:

```html
<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,

```html
    <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](https://jitsu.com/docs/sending-data/js-sdk/privacy-mode). |
| `respectGlobalPrivacyControl` | To respect the user's [GPC](https://globalprivacycontrol.org/) 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.

```javascript
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.

```javascript
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.

```javascript
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](https://gitlab.com/gitlab-org/analytics-section/product-analytics/devkit/-/tree/main#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](https://gitlab.com/gitlab-org/analytics-section/product-analytics/devkit/-/tree/main#test-credentials).
1. Note down the `app_id` that is returned from the configurator.
1. Modify `examples/vanilla-js/src/index.js` to point at your local devkit and project
```javascript
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`.
1. Run the example by running `yarn serve` within `examples/vanilla-js`
1. 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](https://gitlab.com/gitlab-org/analytics-section/product-analytics/devkit/-/tree/main#test-credentials).
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

---
_Source: https://npm.io/package/@gitlab/application-sdk-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._