Merge pull request #7682 from segmentio/Analytics.js-edits-2

More Analytics.js cleanup

Author: rchinn1

src/connections/sources/catalog/libraries/website/javascript/faq.md

@@ -9,16 +9,16 @@ Analytics.js doesn't automatically collect IPv6 addresses. If IPv6 is available
 
 ## Is there a size limit on requests?
 
-Yes, the limit is 32KB per event message. Events with a payload larger than 32KB are not accepted by Analytics.js. Segment servers return a 400 response with the error message: `Exceed payload limit`.
+Yes, the limit is 32 KB per event message. Events with a payload larger than 32 KB are not accepted by Analytics.js. Segment servers return a 400 response with the error message: `Exceed payload limit`.
 
 ## If Analytics.js fails to load, are callbacks not fired?
 
-In the event that Analytics.js does not load, callbacks passed into your API calls do not fire. This is as designed, because the purpose of callbacks are to provide an estimate that the event was delivered and if the library never loads, the events won't be delivered.
+In the event that Analytics.js does not load, callbacks passed into your API calls do not fire. This is by design, because the purpose of a callback is to provide an indication that the event was delivered. If the library never loads, the events won't be delivered.
 
 ## Is there an updated version of the Segment snippet?
 Segment released an updated version of the Analytics.js snippet, which introduces several enhancements and fixes that might improve your setup. For a full list of version updates, see the Analytics.js snippet's [Releases](https://github.com/segmentio/snippet/releases){:target="_blank”}.
 
-You can find the latest version of the Segment snippet in your JavaScript source's Overview tab or in the [Quickstart: Analytics.js](/docs/connections/sources/catalog/libraries/website/javascript/quickstart/#step-2a-add-the-segment-snippet) documentation.
+You can find the latest version of the Segment snippet in your JavaScript source's **Overview** tab or in the [Quickstart: Analytics.js](/docs/connections/sources/catalog/libraries/website/javascript/quickstart/#step-2a-add-the-segment-snippet) documentation.
 
 While there is no deadline to upgrade your snippet to the latest version, upgrading lets you use the latest improvements in the Segment library.
 
@@ -27,16 +27,16 @@ While there is no deadline to upgrade your snippet to the latest version, upgrad
 
 In May 2018, Segment began collecting client-side performance metrics in Analytics.js. This includes metrics like:
 
-- When client side integrations are initialized and when they fail
-- When messages are sent to client side integrations and when they fail
+- When client-side integrations are initialized and when they fail
+- When messages are sent to client-side integrations and when they fail
 
-Segment added these metrics to proactively identify and resolve issues with individual client-side integrations. These metrics are connected to alerts that notify Segment's on-call engineers to take action on these quickly.
+Segment added these metrics to proactively identify and resolve issues with individual client-side integrations. These metrics trigger alerts that notify Segment's on-call engineers to take action promptly.
 
 There should be no noticeable impact to your data flow. You may notice Analytics.js make an extra network request in the network tab to carry the metrics data to Segment's servers. This extra network request is not made frequently, since the data is sampled and batched every 30 seconds.
 
 ## How are properties with `null` and `undefined` values treated?
 
-Segment treats property values set to `null` as null values and drops events set to`undefined`.
+Segment treats property values set to `null` as null values and drops events set to `undefined`.
 
 For example:
 
@@ -48,6 +48,7 @@ console.log(JSON.stringify({ x: undefined, y: 6 }));
 // expected output: "{"y":6}"
 ```
 Segment uses the [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify){:target="blank"} method under the hood. 
+
 ## Can I overwrite the context fields?
 
 Yes. This can be useful if some of these fields contain information you don't want to collect.
@@ -65,7 +66,7 @@ analytics.track("Receipt Viewed", {}, {
 ```
 This works for any [context field](/docs/connections/spec/common/#context) that Segment automatically collects.
 
-When working with Page calls, you can overwrite context fields by following the above instructions. However, because the `context.page` fields are also available in the `properties` parameter for page calls, you must also prevent the same fields in the `properties` parameter from being included in your Page call. Use the code in the following example to overwrite `url` available in context field `page.url` and properties parameter:
+When working with Page calls, you can overwrite context fields by following the above instructions. However, because the `context.page` fields are also available in the `properties` parameter for Page calls, you must also prevent the same fields in the `properties` parameter from being included in your Page call. Use the code in the following example to overwrite `url` available in context field `page.url` and properties parameter:
 
 ```js
 analytics.page("Receipt Page", {
@@ -79,7 +80,7 @@ analytics.page("Receipt Page", {
 
 ## Can I add context fields that do not already exist?
 
-Yes. You can add context fields by passing them into the options object as the third argument of the event call. For example, the analytics.js library does not automatically collect location information, but you can add it to the context object. To add location information into the context object, pass it into the third argument as in the following example:
+Yes. You can add context fields by passing them into the options object as the third argument of the event call. For example, the Analytics.js library does not automatically collect location information, but you can add it to the context object. To add location information into the context object, pass it into the third argument as in the following example:
 
 ```js
 analytics.track("Order Completed", {}, {
@@ -97,7 +98,7 @@ Some destinations accept properties only. As a result, custom context fields you
 
 ## What is the impact of exposing the source's write keys?
 
-Segment's library architecture requires you to expose the write key for client-side tracking to work. Other major tools, like Google Analytics, Mixpanel, Kissmetrics, Hubspot, and Marketo, also require you to expose your write key.
+Segment's library architecture requires you to expose the write key for client-side tracking to work. Other major tools, like Google Analytics, Mixpanel, Kissmetrics, HubSpot, and Marketo, also require you to expose your write key.
 
 If you see any unusual behavior associated with your write key, generate a new key immediately. To generate a new key, navigate to **Connections > Sources** and select your source. On the **Settings** tab, go to the **API Keys** section and click **Generate New Key**.
 
@@ -126,7 +127,7 @@ You'll also need to modify the Segment script with your `nonce` tag, which shoul
 
 ## How is the referrer value set?
 
-The Analytics.js library sets the `context.page.referrer` value from the [`window.document.referrer` property](https://developer.mozilla.org/en-US/docs/Web/API/Document/referrer){:target="_blank"} set in the browser. If you notice unexpected referrer values reaching Segment, check how this value is being set on your website.
+The Analytics.js library sets the `context.page.referrer` value from the [`window.document.referrer` property](https://developer.mozilla.org/en-US/docs/Web/API/Document/referrer){:target="_blank"} set in the browser. If you notice unexpected referrer values reaching Segment, check how this value is set on your website.
 
 ## Are there any rate limits in place for the CDN settings endpoint?
 
@@ -142,4 +143,4 @@ If you need this functionality, you have a couple of options:
 **Use a third-party API**: Alternatively, you can use third-party services like Geolocation API to convert IP addresses to geolocation data. Afterward, you can pass this information as a trait in Identify calls or as a property in Track calls to Segment. This allows you to manage geolocation data according to your specific needs, though it will likely require engineering resources.
 
 ## Why is my payload populating incorrectly?
-Payload parameters aren't populated in a guaranteed order. Your payload should still be ingested as long as all necessary parameters are included.
+Payload parameters aren't populated in a guaranteed order. Your payload will still be ingested as long as all necessary parameters are included.

src/connections/sources/catalog/libraries/website/javascript/identity.md

@@ -3,11 +3,11 @@ title: Managing identity in Analytics.js
 strat: ajs
 ---
 
-This page explains how Analytics.js identifies users, and passes userID and anonymousID data, and how to override and change this information.
+This page explains how Analytics.js identifies users, passes `userID` and `anonymousID` data, and how to override and change this information.
 
-## Segment ID Persistence
+## Segment ID persistence
 
-To ensure high fidelity, first-party customer data, Segment writes the user's IDs to the user's local storage, and uses that as the Segment ID on the cookie whenever possible. Local Storage is meant for storing this type of first-party customer information.
+To ensure high fidelity, first-party customer data, Segment writes the user's IDs to the user's local storage, and uses that as the Segment ID on the cookie whenever possible. Local storage is meant for storing this type of first-party customer information.
 
 If a user returns to your site after the cookie expires, Analytics.js looks for an old ID in the user's `localStorage`, and if one is found, sets it as the user's ID again in the new cookie. If a user clears their cookies _and_ `localstorage`, all of the IDs are removed, and the user gets a completely new `anonymousID` when they next visit the page.
 
@@ -30,8 +30,8 @@ Example:
 ajs_anonymous_id=%2239ee7ea5-b6d8-4174-b612-04e1ef3fa952
 ```
 
-You can override the default-generated anonymousID in code using the methods described below:
-- [Set anonymousId from the Segment snippet](#override-the-anonymous-id-from-the-segment-snippet) (before the `ready` method returns)
+You can override the default-generated `anonymousID` in code using the methods described below:
+- [Set anonymousId from the Segment snippet](#override-the-anonymous-id-from-the-segment-snippet) (before the Ready method returns)
 - [Use a call to override the anonymousID](#override-the-default-anonymous-id-with-a-call)
 - [Set `anonymousId` in the `options` object of a call](#override-the-anonymous-id-using-the-options-object)
 
@@ -43,9 +43,9 @@ You can get the user's current `anonymousId` using the following call:
 analytics.user().anonymousId();
 ```
 
-If the user's `anonymousId` is `null` (meaning not set) when you call this function, Analytics.js automatically generated and sets a new `anonymousId` for the user.
+If the user's `anonymousId` is `null` (meaning not set) when you call this function, Analytics.js automatically generates and sets a new `anonymousId` for the user.
 
-If you are using the npm library, the previous call returns a promise for `user()`. As a workaround, you'll need to grab the user's current `anonymousId` in the following way: 
+If you're using the npm library, the previous call returns a promise for `user()`. As a workaround, you'll need to grab the user's current `anonymousId` in the following way: 
 
 ```js
 analytics.instance?.user().anonymousId()
@@ -57,28 +57,28 @@ A user's `anonymousId` changes when any of the following conditions are met.
 
 - The user clears their cookies _and_ `localstorage`.
 - Your site or app calls [`analytics.reset()`](/docs/connections/sources/catalog/libraries/website/javascript/#reset-or-logout) during in the user's browser session.
-- Your site or app calls `analytics.identify()` with a userId that is different from the current userId.
-- Your site or app is setting `ajs_user_id` to an empty string or calling `analytics.user().id('')` before calling `analytics.identify()`. This sequence of events will result in a new anonymousId being set when `analytics.identify()` is called.
+- Your site or app calls `analytics.identify()` with a `userId` that is different from the current `userId`.
+- Your site or app is setting `ajs_user_id` to an empty string or calling `analytics.user().id('')` before calling `analytics.identify()`. This sequence of events will result in a new `anonymousId` being set when `analytics.identify()` is called.
 
 
 ### Override the Anonymous ID from the Segment snippet
 
-You can also set the `anonymousId` immediately inside your Segment snippet, even before the `ready` method returns.
+You can also set the `anonymousId` immediately inside your Segment snippet, even before the Ready method returns.
 
  ```js
   analytics.load('writekey');
   analytics.page();
   analytics.setAnonymousId('ABC-123-XYZ');
 ```
 
-Use this method if you are queueing calls before `ready` returns and they require a custom `anonymousId`. Keep in mind that setting the `anonymousId` in Analytics.js does not overwrite the anonymous tracking IDs for any destinations you're using.
+Use this method if you are queueing calls before Ready returns and they require a custom `anonymousId`. Keep in mind that setting the `anonymousId` in Analytics.js does not overwrite the anonymous tracking IDs for any destinations you're using.
 
 > info ""
-> Device-mode destinations that load their code on your site _might_ also set their own anonymous ID for the user that is separate and different from the Segment generated one. Some destinations use the Segment `anonymousId`. Read the documentation for each Destination to find out if a Destination sets its own ID.
+> Device-mode destinations that load their code on your site _might_ also set their own anonymous ID for the user that is separate and different from the Segment generated one. Some destinations use the Segment `anonymousId`. Read the documentation for each destination to find out if a destination sets its own ID.
 
 ### Override the default Anonymous ID with a call
 
-If the default generated UUID does not meet your needs, you can override it `anonymousId` for the current user using either of the following methods.
+If the default generated UUID does not meet your needs, you can override the `anonymousId` for the current user with either of the following methods:
 
 ```js
 analytics.user().anonymousId('ABC-123-XYZ');
@@ -92,17 +92,19 @@ These methods behave exactly the same.
 
 ### Override the Anonymous ID using the options object
 
-Or in the `options` object of [`identify`](/docs/connections/spec/identify/), [`page`](/docs/connections/spec/page/), or [`track`](/docs/connections/spec/track/) calls, like this:
+You can override the `anonymousID` in the `options` object of [Identify](/docs/connections/spec/identify/), [Page](/docs/connections/spec/page/), or [Track](/docs/connections/spec/track/) calls, like this:
 
 
-Set the anonymousId in the Options object using the format in the following examples.
+Set the `anonymousId` in the `options` object using the format in the following examples.
 
-The custom anonymousId persists when you use these methods, even if you do not explicitly specify the anonymousId in the calls.
+The custom `anonymousId` persists when you use these methods, even if you do not explicitly specify the `anonymousId` in the calls.
 
-For example, after the Track call below sets the anonId, any later track calls from this user will have the anonymousId of `ABC-123-XYZ`, even if it is not explicitly specified in the track call.
+For example, after a Track call sets the `anonymousID` to `ABC-123-XYZ`, any additional Track calls from this user will have the same `anonymousId`, even if it's not explicitly specified in the Track call.
 
 #### Override anonymousId in an Identify call
 
+You can override `anonymousID` with an Identify call. For example:
+
 ```js
 analytics.identify('user_123', {
   name: 'Jane Kim'
@@ -113,12 +115,16 @@ analytics.identify('user_123', {
 
 #### Override anonymousId on a Page call
 
+You can override `anonymousID` with a Page call. For example:
+
 ```js
 analytics.page({}, { anonymousId: 'ABC-123-XYZ' });
 ```
 
 #### Override anonymousId on a Track call
 
+You can override `anonymousID` with a Track call. For example:
+
 ```js
 analytics.track('Email Clicked', {
   callToAction: 'Signup'
@@ -146,7 +152,7 @@ Consider this Identify event:
 ```js
 analytics.identify('12091906-01011992', {
     plan_id: 'Paid, Tier 2',
-    email: 'grace@usnavy.gov'
+    email: 'grace@example.com'
 });
 ```
 
@@ -166,7 +172,7 @@ analytics.track('Clicked Email', {
 );
 ```
 
-This appends the `plan_id` trait to this Track event. This does _not_ add the name or email, since those traits were not added to the `context` object. You must do this for every following event you want these traits to appear on, as the `traits` object does not persist between calls.
+This appends the `plan_id` trait to the Track event. This does _not_ add the name or email, since those traits were not added to the `context` object. You must do this for every following event you want these traits to appear on, as the `traits` object does not persist between calls.
 
 By default, non-Identify events (like Track or Page) **don't automatically collect user traits** from previous Identify calls. To include traits from an `identify()` event in later events, you'll need to add them manually to the `context.traits` object within the `options` parameter.
 
@@ -180,9 +186,9 @@ Each Analytics.js method has an `options` parameter where you can pass the `cont
 Adding traits to events is especially useful if you're using [Actions destinations](/docs/connections/destinations/actions/), since it makes those traits available for mapping in the destination’s configuration.
 
 
-## Clearing Traits
+## Clearing traits
 
-You can pass an empty object to the `traits` object to clear _all_ cached traits for a User or Group.
+You can pass an empty object to the `traits` object to clear _all_ cached traits for a user or group.
 
 Traits are cached by default when you call the Identify and Group methods. You can clear the `traits` object for the user or group by passing `traits` an empty object:
 
@@ -195,13 +201,13 @@ analytics.group().traits({});
 
 ## Using analytics.user() and analytics.group() 
 
-You can use the `user` or `group` method as soon as the Analytics.js library loads, to return information about the currently identified user or group. This information is retrieved from the user's cookie.
+You can use the User or Group method as soon as the Analytics.js library loads, to return information about the currently identified user or group. This information is retrieved from the user's cookie.
 
 <!-- TODO: retrieves info from cookie, if they have any info - maybe link to the top section-->
 
 
 > success ""
-> **Tip:** You can wrap any reference to `user()` or `group()` in a [ready function block](/docs/connections/sources/catalog/libraries/website/javascript#ready) to ensure that Analytics.js has fully loaded so these methods are available.
+> You can wrap any reference to `user()` or `group()` in a [ready function block](/docs/connections/sources/catalog/libraries/website/javascript#ready) to ensure that Analytics.js has fully loaded so these methods are available.
 
 Examples:
 
@@ -228,7 +234,7 @@ analytics.ready(function() {
 
 ## Anonymizing IP
 
-Segment automatically collects the user's IP address for device-based (iOS, Android, Analytics.js and Xamarin) events.
+Segment automatically collects the user's IP address for device-based (iOS, Android, Analytics.js, and Xamarin) events.
 
 > info "IPv6"
 > At the moment, Segment doesn't support automatically collecting IPv6 addresses.