npm package: @rebilly/lead-source-tracker
Description: Simple library which is used to collect and store lead source information into a cookie
Author: Rebilly
Latest version: 8.15.1

# lead-source-tracker
Simple library which is used to collect and store lead source information into a cookie

## Contributing

1. Clone the repo and run `yarn && yarn serve`
2. Open `127.0.0.1:3001` and check the console to view the tracker in action. (**Note**: `localhost:3001` won't work due to an obscure bug in the way browsers handle cookies)
3. You can test collecting information on `127.0.0.1:3001` using either Query params or `#rls-token` (explained below)
4. Kill and re-run `yarn serve`, and then refresh `127.0.0.1:3001` after making changes to the source code.

## Usage

1. Add the package to your project

`yarn add @rebilly/lead-source-tracker`

2. Import `RebillyLeadSource` on each page you would like to track

`import RebillyLeadSource from '@rebilly/lead-source-tracker';`

3. Call the `collect` function on each page load to have the tracker collect and save information to the cookie. 

`RebillyLeadSource.collect(window)`

You can provide additional cookie attribues using the second argument:


`RebillyLeadSource.collect(window, { domain: 'rebilly.com', secure: true })`

See https://github.com/js-cookie/js-cookie#cookie-attributes for the full list of supported attributes.

4. Call `collect` again when submitting lead source information to the Rebilly API. The function returns all saved cookie data as an object.

Example:
```
const endpoint = 'https://api.rebilly.com/storefront/v1/register';

const leadSource = RebillyLeadSource.collect(window);

const body = {
    username: email,
    password: generatePassword(),
    primaryAddress: {
        firstName,
        lastName,
    },
    leadSource,
}

fetch(endpoint, {
    method: 'POST',
    headers,
    body: JSON.stringify(body)
})
```

**Note:** `collect` can only be called from the browser, it will throw an exception if called from a node server. 
In SSR frameworks like gatsby, this means the function should be called from within an appropriate hook (e.g. `useEffect`).

## leadSource data sources

This section lists all the possible ways to provide `RebillyLeadSource` with leadSource data.

`path` and `referrer` will not be updated after the first time they have been saved to the cookie.

### Automatically gathered

Some data is automatically inferred by `RebillyLeadSource` when data collection happens:

1. `document.referrer` / HTTP `referer` header
    - saved to the leadSource.referrer field

2. `document.location`
    - URL is parsed and saved to leadSource.path

### Query params

| key | example                             | purpose                                                                   |
| --- | ----------------------------------- | ------------------------------------------------------------------------- |
| `dnt` | `?dnt=true`                         | Setting `dnt` will cause RebillyLeadSource to stop tracking that user.    |
| `source` | `?source=example` | Change the leadSource `source` field | 
| `medium` | `?medium=example` | Change the leadSource `medium` field | 
| `campaign` | `?campaign=example` | Change the leadSource `campaign` field | 
| `term` | `?term=example` | Change the leadSource `term` field | 
| `content` | `?content=example` | Change the leadSource `content` field | 
| `affiliate` | `?affiliate=example` | Change the leadSource `affiliate` field | 
| `subAffiliate` or `subaffiliate` | `?subAffiliate=example` | Change the leadSource `subAffiliate` field | 
| `clickId` or `clickid` | `?clickId=example` | Change the leadSource `clickId` field | 
| `salesAgent` or `salesagent` | `?salesAgent=example` | Change the leadSource `salesAgent` field | 
| `path` | `?path=example` | Change the leadSource `path` field. This cannot be updated once it is set the first time | 
| `referrer` | `?referrer=example` | Change the leadSource `referrer` field. This cannot be updated once it is set the first time | 

All leadSource query params will also work if prefixed with `utm_`. e.g. `?utm_campaign=campaign1`

### `#rls-token`

We may want to embed into a page some leadSource information which we know will always be valid.

When `RebillyLeadSource` collects data, it will search the DOM for an element with the ID `#rls-token`.
leadSource data can be added to this element using `data-` attributes.

```html
<body>
    ...
    <div
        id="rls-token"
        data-medium="..."
        data-source="..."
        data-campaign="..."
        data-term="..."
        data-content="..."
        data-affiliate="..."
        data-sub-affiliate="..."
        data-sales-agent="..."
        data-click-id="..."
        data-path="..."
        data-referrer="..." />
</body>
```

## Updatable vs Immutable fields

The following fields will not be updated after the first time they are saved to the cookie:

- path
- referrer

The only exception is if the cookie expires (after 45 days) or is cleared by the user.

All other fields will update the saved cookie whenever `collect` is called.