From 5f2647844f8a404db839668ad581c9ff6eee81c5 Mon Sep 17 00:00:00 2001 From: stayseesong Date: Fri, 1 Apr 2022 13:47:41 -0700 Subject: [PATCH 1/3] [netlify-build] --- .../libraries/website/javascript/index.md | 244 ++++-------------- .../website/javascript/upgrade-to-ajs2.md | 8 +- 2 files changed, 57 insertions(+), 195 deletions(-) diff --git a/src/connections/sources/catalog/libraries/website/javascript/index.md b/src/connections/sources/catalog/libraries/website/javascript/index.md index b7d6a68d5a..473d278261 100644 --- a/src/connections/sources/catalog/libraries/website/javascript/index.md +++ b/src/connections/sources/catalog/libraries/website/javascript/index.md @@ -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"}. +>

All sources created on April 5, 2022 and after default to use Analytics.js 2.0. ## Benefits of Analytics.js 2.0 @@ -70,33 +71,12 @@ analytics.identify([userId], [traits], [options], [callback]); The Identify call has the following fields: - - - - - - - - - - - - - - - - - - - - - - - - - -
`userId`optionalStringThe 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`optionalObjectA 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`optionalObjectA 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`optionalFunctionA function executed after a short timeout, giving the browser time to make outbound requests first.
- +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. @@ -141,32 +121,12 @@ analytics.track(event, [properties], [options], [callback]); The `track` call has the following fields: - - - - - - - - - - - - - - - - - - - - - - - - - -
`event`StringThe name of the event you're tracking. You can read more about the [track method](/docs/connections/spec/track) and recommended event names.
`properties`optionalObjectA 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`optionalObjectA 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`optionalFunctionA function that runs after a short timeout, giving the browser time to make outbound requests first.
+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). @@ -195,23 +155,11 @@ The `trackLink` method follows the format below. analytics.trackLink(element, event, [properties]) ``` - - - - - - - - - - - - - - - - -
`element(s)` Element or ArrayDOM 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 FunctionThe 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` optionalObject or FunctionA dictionary of properties to pass with the track method or a **function** that returns an object to use as the `properties` of the event.
+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: @@ -234,23 +182,12 @@ The `trackForm` method follows the format below. analytics.trackForm(form, event, [properties]) ``` - - - - - - - - - - - - - - - - -
`form(s)` Element or ArrayElement or ArrayThe form element to track or an array of form elements or jQuery objects. _Note: trackForm takes an element, not a CSS selector._
`event` String or FunctionThe 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` optionalObject or FunctionA dictionary of properties to pass with the track method. Or a **function** that returns an object to use as the `properties` of the event.
+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: @@ -279,39 +216,13 @@ analytics.page([category], [name], [properties], [options], [callback]); The `page` call has the following fields: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
`category`optionalStringThe 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 StringThe 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`optionalObjectA 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`optionalFunctionA function that runs after a short timeout, giving the browser time to make outbound requests first.
- +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 @@ -365,33 +276,12 @@ analytics.group(groupId, [traits], [options], [callback]); ``` The Group call has the following fields: - - - - - - - - - - - - - - - - - - - - - - - - - -
`groupId`StringThe Group ID to associate with the current user.
`traits`optional ObjectA dictionary of [traits](/docs/connections/spec/group#traits) for the group. Example traits for a group include `address`, `website`, and `employees`.
`options`optionalObjectA 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`optionalFunctionA function that runs after a short timeout, giving the browser time to make outbound requests first.
- +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: @@ -422,32 +312,12 @@ analytics.alias(userId, [previousId], [options], [callback]); The Alias call has the following fields: - - - - - - - - - - - - - - - - - - - - - - - - - -
`userId`StringThe new user ID you want to associate with the user.
`previousId`optionalStringThe previous ID that the user was recognized by. This defaults to the currently identified user's ID.
`options`optionalObjectA dictionary of options. For example, [enable or disable specific destinations](#managing-data-flow-with-the-integrations-object) for the call.
`callback`optionalFunctionA function that is executed after a short timeout, giving the browser time to make outbound requests first.
+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/). @@ -487,13 +357,9 @@ analytics.ready(callback); The `ready` method has the following fields: - - - - - - -
`callback` FunctionA function to be executed after all enabled destinations have loaded.
+Field | Type | Description +----- | ---- | ----------- +`callback` | Function | A function to be executed after all enabled destinations have loaded. ### Debug @@ -520,18 +386,10 @@ Use the `on` method to set listeners for these events and run your own custom co analytics.on(method, callback); ``` - - - - - - - - - - - -
`method` StringName of the method to listen for
`callback` FunctionA function to execute after each emitted method, taking three arguments: `event`, `properties`, `options`
+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: diff --git a/src/connections/sources/catalog/libraries/website/javascript/upgrade-to-ajs2.md b/src/connections/sources/catalog/libraries/website/javascript/upgrade-to-ajs2.md index 15ccb4529b..e47d7cfb23 100644 --- a/src/connections/sources/catalog/libraries/website/javascript/upgrade-to-ajs2.md +++ b/src/connections/sources/catalog/libraries/website/javascript/upgrade-to-ajs2.md @@ -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. @@ -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 From 2b243cbf0ed4858969dc67355b1e8887dbaf2e40 Mon Sep 17 00:00:00 2001 From: stayseesong <83784848+stayseesong@users.noreply.github.com> Date: Mon, 4 Apr 2022 11:51:26 -0700 Subject: [PATCH 2/3] Update src/connections/sources/catalog/libraries/website/javascript/index.md Co-authored-by: forstisabella <92472883+forstisabella@users.noreply.github.com> --- .../sources/catalog/libraries/website/javascript/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/sources/catalog/libraries/website/javascript/index.md b/src/connections/sources/catalog/libraries/website/javascript/index.md index 473d278261..389e769b48 100644 --- a/src/connections/sources/catalog/libraries/website/javascript/index.md +++ b/src/connections/sources/catalog/libraries/website/javascript/index.md @@ -75,7 +75,7 @@ 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`. +`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. From 57e0213c3cac26273abd78553569da2e4f28d512 Mon Sep 17 00:00:00 2001 From: stayseesong <83784848+stayseesong@users.noreply.github.com> Date: Mon, 4 Apr 2022 12:02:33 -0700 Subject: [PATCH 3/3] Update src/connections/sources/catalog/libraries/website/javascript/index.md --- .../sources/catalog/libraries/website/javascript/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/sources/catalog/libraries/website/javascript/index.md b/src/connections/sources/catalog/libraries/website/javascript/index.md index 389e769b48..c9eedb3891 100644 --- a/src/connections/sources/catalog/libraries/website/javascript/index.md +++ b/src/connections/sources/catalog/libraries/website/javascript/index.md @@ -125,7 +125,7 @@ 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*_ +`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).