Skip to content

A.js 2.0 minor doc updates [DOC-490] #2696

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 4, 2022
Merged

A.js 2.0 minor doc updates [DOC-490] #2696

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5f26478
[netlify-build]
stayseesong Apr 1, 2022
2b243cb
Update src/connections/sources/catalog/libraries/website/javascript/i…
stayseesong Apr 4, 2022
57e0213
Update src/connections/sources/catalog/libraries/website/javascript/i…
stayseesong Apr 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
244 changes: 51 additions & 193 deletions src/connections/sources/catalog/libraries/website/javascript/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,9 @@ id: IqDTy1TpoU
---
Analytics.js 2.0, the latest version of Segment's JavaScript source, enables you to send your data to any tool without having to learn, test, or use a new API every time.

> note ""
> info ""
> Analytics.js 2.0 is available as an [open-source project](https://github.com/segmentio/analytics-next/){:target="_blank"}.
> <br><br> All sources created on April 5, 2022 and after default to use Analytics.js 2.0.


## Benefits of Analytics.js 2.0
Expand Down Expand Up @@ -70,33 +71,12 @@ analytics.identify([userId], [traits], [options], [callback]);

The Identify call has the following fields:

<table>
<tr>
<td>`userId`</td>
<td>optional</td>
<td>String</td>
<td>The database ID for the user. If you don't know who the user is yet, you can omit the `userId` and just record `traits`. You can read more about identities in the [identify reference](/docs/connections/spec/identify).</td>
</tr>
<tr>
<td>`traits`</td>
<td>optional</td>
<td>Object</td>
<td>A dictionary of traits you know about the user, like `email` or `name`. You can read more about traits in the [identify reference](/docs/connections/spec/identify/).</td>
</tr>
<tr>
<td>`options`</td>
<td>optional</td>
<td>Object</td>
<td>A dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call. _Note: If you do not pass a `traits` object, pass an empty object (as an '{}') before `options`_</td>
</tr>
<tr>
<td>`callback`</td>
<td>optional</td>
<td>Function</td>
<td>A function executed after a short timeout, giving the browser time to make outbound requests first.</td>
</tr>
</table>

Field | | Type | Description
----- | | ---- | -----------
`userId` | optional | String | The database ID for the user. If you don't know who the user is yet, you can omit the `userId` and just record `traits`. You can read more about identities in the [identify reference](/docs/connections/spec/identify).
`traits` | optional | Object | A dictionary of traits you know about the user, like `email` or `name`. You can read more about traits in the [identify reference](/docs/connections/spec/identify/).
`options` | optional | Object | A dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call. _Note: If you do not pass a `traits` object, pass an empty object (as an '{}') before `options`._
`callback` | optional | Function | A function executed after a short timeout, giving the browser time to make outbound requests first.

By default, Analytics.js caches traits in the browser's `localStorage` and attaches them to each Identify call.

Expand Down Expand Up @@ -141,32 +121,12 @@ analytics.track(event, [properties], [options], [callback]);

The `track` call has the following fields:

<table>
<tr>
<td>`event`</td>
<td></td>
<td>String</td>
<td>The name of the event you're tracking. You can read more about the [track method](/docs/connections/spec/track) and recommended event names.</td>
</tr>
<tr>
<td>`properties`</td>
<td>optional</td>
<td>Object</td>
<td>A dictionary of [properties](/docs/connections/spec/track#properties) for the event. If the event was `'Added to Cart'`, it might have properties like `price` and `productType`.</td>
</tr>
<tr>
<td>`options`</td>
<td>optional</td>
<td>Object</td>
<td>A dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call. _Note: If you do not pass a `properties` object, pass an empty object (like '{}') before *options*_</td>
</tr>
<tr>
<td>`callback`</td>
<td>optional</td>
<td>Function</td>
<td>A function that runs after a short timeout, giving the browser time to make outbound requests first.</td>
</tr>
</table>
Field | | Type | Description
----- | | ---- | -----------
`event`| | String | The name of the event you're tracking. You can read more about the [track method](/docs/connections/spec/track) and recommended event names.
`properties` | optional | Object | A dictionary of [properties](/docs/connections/spec/track#properties) for the event. If the event was `'Added to Cart'`, it might have properties like `price` and `productType`.
`options` | optional | Object | A dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call. _Note: If you do not pass a `properties` object, pass an empty object (like '{}') before `options`_.
`callback` | optional | Function | A function that runs after a short timeout, giving the browser time to make outbound requests first.

The only required argument in Analytics.js is an _event name string_. You can read more about [how Segment recommends you name events](/docs/connections/spec/track#event).

Expand Down Expand Up @@ -195,23 +155,11 @@ The `trackLink` method follows the format below.
analytics.trackLink(element, event, [properties])
```

<table>
<tr>
<td>`element(s)` </td>
<td>Element or Array</td>
<td>DOM element to bind with `track` method. You may pass an array of elements or jQuery objects. _Note: This must be an element, **not** a CSS selector._</td>
</tr>
<tr>
<td>`event` </td>
<td>String or Function</td>
<td>The name of the event, passed to the `track` method. Or a **function** that returns a string to use as the name of the `track` event.</td>
</tr>
<tr>
<td>`properties` optional</td>
<td>Object or Function</td>
<td>A dictionary of properties to pass with the track method or a **function** that returns an object to use as the `properties` of the event.</td>
</tr>
</table>
Field | | Type | Description
----- | | ---- | -----------
`element(s)` | | Element or Array | DOM element to bind with `track` method. You may pass an array of elements or jQuery objects. _Note: This must be an element, **not** a CSS selector._
`event` | | String or Function | The name of the event, passed to the `track` method. Or a **function** that returns a string to use as the name of the `track` event.
`properties` | optional | Object or Function | A dictionary of properties to pass with the track method or a **function** that returns an object to use as the `properties` of the event.

Example:

Expand All @@ -234,23 +182,12 @@ The `trackForm` method follows the format below.
analytics.trackForm(form, event, [properties])
```

<table>
<tr>
<td>`form(s)` Element or Array</td>
<td>Element or Array</td>
<td>The form element to track or an array of form elements or jQuery objects. _Note: trackForm takes an element, not a CSS selector._</td>
</tr>
<tr>
<td>`event` </td>
<td>String or Function</td>
<td>The name of the event, passed to the `track` method. Or a **function** that returns a string to use as the name of the `track` event.</td>
</tr>
<tr>
<td>`properties` optional</td>
<td>Object or Function</td>
<td>A dictionary of properties to pass with the track method. Or a **function** that returns an object to use as the `properties` of the event.</td>
</tr>
</table>
Field | | Type | Description
----- | | ---- | -----------
`form(s)` | | Element or Array | The form element to track or an array of form elements or jQuery objects. _Note: trackForm takes an element, not a CSS selector._
`event` | | Element or Array | The form element to track or an array of form elements or jQuery objects. _Note: trackForm takes an element, not a CSS selector._
`form(s)` | | Element or Array | The form element to track or an array of form elements or jQuery objects. _Note: trackForm takes an element, not a CSS selector._
`properties` | optional | Object or Function | A dictionary of properties to pass with the track method. Or a **function** that returns an object to use as the `properties` of the event.

Example:

Expand Down Expand Up @@ -279,39 +216,13 @@ analytics.page([category], [name], [properties], [options], [callback]);

The `page` call has the following fields:

<table>
<tr>
<td>`category`</td>
<td>optional</td>
<td>String</td>
<td>The category of the page. Useful for cases like ecommerce where many pages might live under a single category. _Note: if you pass only one string to `page` it is assumed to be `name`. You **must** include a `name` to send a `category`._</td>
</tr>
<tr>
<td>`name`</td>
<td>optional</td>
<td> String</td>
<td>The name of the page.</td>
</tr>
<tr>
<td>`properties`</td>
<td>optional</td>
<td> Object </td>
<td>A dictionary of properties of the page. Note: Analytics.js collects `url`, `title`, `referrer` and `path` are automatically. This defaults to a `canonical url`, if available, and falls back to `document.location.href`.</td>
</tr>
<tr>
<td>`options`</td>
<td>optional</td>
<td>Object</td>
<td>A dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call. _Note: If you do not pass a `properties` object, pass an empty object (like '{}') before `options`_ </td>
</tr>
<tr>
<td>`callback`</td>
<td>optional</td>
<td>Function</td>
<td>A function that runs after a short timeout, giving the browser time to make outbound requests first.</td>
</tr>
</table>

Field | | Type | Description
----- | | ---- | -----------
`category` | optional | String | The category of the page. Useful for cases like ecommerce where many pages might live under a single category. _Note: if you pass only one string to `page` it is assumed to be `name`. You **must** include a `name` to send a `category`._
`name` | optional | String | The name of the page.
`properties` | optional | Object | A dictionary of properties of the page. Note: Analytics.js collects `url`, `title`, `referrer` and `path` are automatically. This defaults to a `canonical url`, if available, and falls back to `document.location.href`.
`options` | optional | Object | A dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call. _Note: If you do not pass a `properties` object, pass an empty object (like '{}') before `options`_.
`callback` | optional | Function | A function that runs after a short timeout, giving the browser time to make outbound requests first.

#### Default Page Properties

Expand Down Expand Up @@ -365,33 +276,12 @@ analytics.group(groupId, [traits], [options], [callback]);
```
The Group call has the following fields:

<table>
<tr>
<td>`groupId`</td>
<td></td>
<td>String</td>
<td>The Group ID to associate with the current user.</td>
</tr>
<tr>
<td>`traits`</td>
<td>optional</td>
<td> Object</td>
<td>A dictionary of [traits](/docs/connections/spec/group#traits) for the group. Example traits for a group include `address`, `website`, and `employees`.</td>
</tr>
<tr>
<td>`options`</td>
<td>optional</td>
<td>Object</td>
<td>A dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call. _Note: If you do not pass a `properties` object, pass an empty object (like '{}') before `options`_</td>
</tr>
<tr>
<td>`callback`</td>
<td>optional</td>
<td>Function</td>
<td>A function that runs after a short timeout, giving the browser time to make outbound requests first.</td>
</tr>
</table>

Field | | Type | Description
----- | | ---- | -----------
`groupId` | | String | The Group ID to associate with the current user.
`traits` | optional | Object | A dictionary of [traits](/docs/connections/spec/group#traits) for the group. Example traits for a group include `address`, `website`, and `employees`.
`options` | optional | Object | A dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call. _Note: If you do not pass a `properties` object, pass an empty object (like '{}') before `options`_.
`callback` | optional | Function | A function that runs after a short timeout, giving the browser time to make outbound requests first.

Example `group` call:

Expand Down Expand Up @@ -422,32 +312,12 @@ analytics.alias(userId, [previousId], [options], [callback]);

The Alias call has the following fields:

<table>
<tr>
<td>`userId`</td>
<td></td>
<td>String</td>
<td>The new user ID you want to associate with the user.</td>
</tr>
<tr>
<td>`previousId`</td>
<td>optional</td>
<td>String</td>
<td>The previous ID that the user was recognized by. This defaults to the currently identified user's ID.</td>
</tr>
<tr>
<td>`options`</td>
<td>optional</td>
<td>Object</td>
<td>A dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call.</td>
</tr>
<tr>
<td>`callback`</td>
<td>optional</td>
<td>Function</td>
<td>A function that is executed after a short timeout, giving the browser time to make outbound requests first.</td>
</tr>
</table>
Field | | Type | Description
----- | | ---- | -----------
`userId` | | String | The new user ID you want to associate with the user.
`previousId` | optional | String | The previous ID that the user was recognized by. This defaults to the currently identified user's ID.
`options` | optional | Object | A dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call.
`callback` | optional | Function | A function that is executed after a short timeout, giving the browser time to make outbound requests first.

For more details about Alias, including the **`alias` call payload**, check out our [Spec](/docs/connections/spec/alias/).

Expand Down Expand Up @@ -487,13 +357,9 @@ analytics.ready(callback);

The `ready` method has the following fields:

<table>
<tr>
<td>`callback` </td>
<td>Function</td>
<td>A function to be executed after all enabled destinations have loaded.</td>
</tr>
</table>
Field | Type | Description
----- | ---- | -----------
`callback` | Function | A function to be executed after all enabled destinations have loaded.

### Debug

Expand All @@ -520,18 +386,10 @@ Use the `on` method to set listeners for these events and run your own custom co
analytics.on(method, callback);
```

<table>
<tr>
<td>`method` </td>
<td>String</td>
<td>Name of the method to listen for</td>
</tr>
<tr>
<td>`callback` </td>
<td>Function</td>
<td>A function to execute after each emitted method, taking three arguments: `event`, `properties`, `options`</td>
</tr>
</table>
Field | Type | Description
----- | ---- | -----------
`method` | String | Name of the method to listen for.
`callback`| Function | A function to execute after each emitted method, taking three arguments: `event`, `properties`, `options`.

Example:

Expand Down
8 changes: 6 additions & 2 deletions src/connections/sources/catalog/libraries/website/javascript/upgrade-to-ajs2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Analytics.js sources will upgrade to Analytics.js 2.0 on the date below, accordi
|--------------| -------------|
| Free | June 15, 2021|
| Team | July 6, 2021 |
| Business | TBD |
| Business | June 2022 |

> info ""
> The plans and dates listed above are subject to change.
Expand All @@ -46,7 +46,11 @@ In some cases, upgrading to Analytics.js 2.0 requires manual effort beyond enabl

### Using in-domain instrumentation CDN aliasing

If the source you intend to upgrade uses the in-domain instrumentation as well as a custom "Alias for analytics.js", then you should update the AJS snippet to the latest version (4.15.3 or higher) before you toggle on Analytics.js 2.0.
If the source you intend to upgrade uses the in-domain instrumentation as well as a custom "Alias for analytics.js", then you should update the Analytics.js snippet to the latest version (4.15.3 or higher) before you toggle on Analytics.js 2.0.

### Using a mix of Analytics.js Classic and 2.0 sources

If you're using a mix of Analytics.js Classic and 2.0 sources, the classic source won't be able to use the anonymous ID set by Analytics.js 2.0. In order to fix this, update all sources to 2.0.

### Relying on Analytics.js Classic's `ajs_anonymous_id` cookie format

Expand Down