Merge pull request ampproject#1897 from ampproject/rudygalfi-analytic…

…s-docs Update analytics docs with new trigger structure
camelburrito · Feb 10, 2016 · 52ab8c6 · 52ab8c6
2 parents 288778f + 7d292ee
commit 52ab8c6
Showing 1 changed file with 89 additions and 52 deletions.
diff --git a/extensions/amp-analytics/amp-analytics.md b/extensions/amp-analytics/amp-analytics.md
@@ -14,11 +14,11 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-# <a name="amp-analytics"></a>`amp-analytics`
+### <a name="amp-analytics"></a>`amp-analytics`
 
 Capture analytics data from an AMP document.
 
-## <a name="behavior"></a>Behavior
+#### <a name="behavior"></a>Behavior
 
 The `<amp-analytics>` element is used to measure activity on an AMP document. The details concerning what is measured and how
 that data is sent to an analytics server is specified in a JSON configuration object.
@@ -57,37 +57,38 @@ when the document is first loaded, and each time an `<a>` tag is clicked:
 </amp-analytics>
 ```
 
-## <a name="attributes"></a>Attributes
+#### <a name="attributes"></a>Attributes
 
-  - `type` This optional attribute can be specified to use one of the built-in analytics providers. Currently supported values for type are:
+  - `type` Optional attribute. This attribute can be used to inherit configuration from one of the built-in analytics providers. Currently supported values for type are:
     - `chartbeat`: Adds support for Chartbeat. More details for adding Chartbeat support can be found at [support.chartbeat.com](http://support.chartbeat.com/docs/).
-    - `comscore`: Supports comScore Unified Digital Measurement™ pageview analytics. Requires defining *var* `c2` with comScore-provided *c2 id*.
+    - `comscore`: Adds support for comScore Unified Digital Measurement™ pageview analytics. Requires defining *var* `c2` with comScore-provided *c2 id*.
     - `googleanalytics`: Adds support for Google Analytics. More details for adding Google Analytics support can be found at [developers.google.com](https://developers.google.com/analytics/devguides/collection/amp-analytics/).
 
+
+    Here's an example of usage of `type` for a provider called XYZ:
     ```
     <amp-analytics type="XYZ"> ... </amp-analytics>
     ```
 
-  - `config` This attribute can be used to load a configuration from a specified remote URL. The URL specified here should use https scheme. See also `data-include-credentials` attribute below.
+  - `config` Optional attribute. This attribute can be used to load a configuration from a specified remote URL. The URL specified here should use https scheme. See also `data-include-credentials` attribute below.
 
     ```
     <amp-analytics config="https://example.com/analytics.config.json"></amp-analytics>
     ```
     The response must follow the [AMP CORS security guidelines](../../spec/amp-cors-requests.md).
-  - `data-credentials` Optional. If set to `include` turns on the ability to read and write cookies on the request specified via `config` above.
-  - `data-consent-notification-id` Optional attribute. If provided will stop
-    processing the analytics request until a [amp-user-notification](../../extensions/amp-user-notification/amp-user-notification.md) with
-    the given HTML-id was confirmed by the user.
+  - `data-credentials` Optional attribute. If set to `include` turns on the ability to read and write cookies on the request specified via `config` above.
+  - `data-consent-notification-id` Optional attribute. If provided, the page will not process analytics requests until an [amp-user-notification](../../extensions/amp-user-notification/amp-user-notification.md) with
+    the given HTML element id is confirmed (accepted) by the user.
 
-## Configuration
+#### Configuration
 
 Configuration may be specified inline (as shown in the example above) or fetched remotely by specifying a URL in the
 `config` attribute. Additionally, built-in configuration for popular analytics vendors can be selected using
 the `type` attribute.
 
-If configuration data from more than one of these sources is used, the configuration objects(vars, requests and triggers) will
-be merged together such that remote configuration takes precedence over inline configuration, and inline configuration
-takes precendence over vendor configuration.
+If configuration data from more than one of these sources is used, the configuration objects (vars, requests and triggers) will
+be merged together such that **(i) remote configuration takes precedence over inline configuration and (ii) inline configuration
+takes precendence over vendor configuration**.
 
 The `<amp-analytics>` configuration object uses the following format:
 
@@ -112,7 +113,7 @@ The `<amp-analytics>` configuration object uses the following format:
   }
 }
 ```
-### Requests
+##### Requests
 The `requests` attribute specifies the URLs used to transmit data to an analytics platform. The `request-name` is used
 in the trigger configuration to specify what request should be sent in response to a pariticular event. The `request-value`
 is an https URL. These values may include placeholder tokens that can reference other requests or variables.
@@ -125,8 +126,8 @@ is an https URL. These values may include placeholder tokens that can reference
 }
 ```
 
-### Vars
-`amp-analytics` defines many basic variables that can be used in requests. A list of all such variables is available [here](./analytics-vars.md). In addition, all the variables supported by [AMP HTML URL Variable Substitutions](../../spec/amp-var-substitutions.md) are also supported.
+##### Vars
+`amp-analytics` defines many basic variables that can be used in requests. A list of all such variables is available in the  [`amp-analytics` Variables Guide](./analytics-vars.md). In addition, all of the variables supported by [AMP HTML Substitutions Guide](../../spec/amp-var-substitutions.md) are also supported.
 
 The `vars` attribute in the configuration can be used to define new key-value pairs or override existing variables that can be referenced in `request` values. New variables are commonly used to specify publisher specific information.
 
@@ -137,56 +138,85 @@ The `vars` attribute in the configuration can be used to define new key-value pa
 }
 ```
 
-### Triggers
+##### Triggers
 The `triggers` attribute describes when an analytics request should be sent. It contains a key-value pair of trigger-name and
  trigger-configuration. Trigger name can be any string comprised of alphanumeric characters (a-zA-Z0-9). Triggers from a
  configuration with lower precedence are overridden by triggers with the same names from a configuration with higher precedence.
 
-  - `on` (required) The event to listener for. Valid values are `visible`,`click`, and `timer`.
+  - `on` (required) The event to listener for. Valid values are `click`, `scroll`, `timer`, and `visible`.
   - `request` (required) Name of the request to send (as specified in the `requests` section).
   - `vars` An object containing key-value pairs used to override `vars` defined in the top level config, or to specify
     vars unique to this trigger.
+  - `selector` (required when `on` is set to `click`) This configuration is used on conjunction with the `click` trigger. Please see below for details.
+  - `scrollSpec` (required when `on` is set to `scroll`) This configuration is used on conjunction with the `scroll` trigger. Please see below for details.
+  - `timerSpec` (required when `on` is set to `timer`) This configuration is used on conjunction with the `timer` trigger. Please see below for details.
 
-Following configuration only applies to specific values of `on`.
-  - `selector` A CSS selector used to refine which elements should be tracked. Use value `*` to track all elements. Used in triggers where `on` is set to `click`.
-  - `scrollSpec` An object used when `on` is set to `scroll`. This object can contain `verticalBoundaries` and `horizontalBoundaries`. At least one of the two property is required for scroll event to fire. The values for both the properties should be arrays of numbers containing the boundaries on which a scroll event is generated. For instance, in the following code snippet, the scroll event will be fired when page is scrolled vertically by 25%, 50% and 90%. Additionally, the event will also fire when the page is horizontally scrolled to 90% of scroll width.
-  - `timerSpec` Specification for triggers of type `timer`. The timer will trigger immediately and then at a specified interval thereafter.
-    - `interval` Length of the timer interval, in seconds.
-    - `maxTimerLength` Maximum duration for which the timer will fire, in seconds.
+###### Page visible trigger (`"on": "visible"`)
+Use this configuration to fire a request when the page becomes visible. No further configuration is required.
 
 ```javascript
 "triggers": {
   "defaultPageview": {
     "on": "visible",
     "request": "pageview"
-  },
-  "anchorClicks": {
-    "on": "click",
-    "selector": "a",
-    "request": "event",
-    "vars": {
-      "eventId": 128
-    }
-  },
-  "pageTimer": {
-    "on": "timer",
-    "timerSpec": {
-      "interval": 10,
-      "maxTimerLength": 600
-    },
-    "request": "pagetime"
-  },
-  "scrollPings": {
-    "on": "scroll",
-    "scrollSpec": {
-      "verticalBoundaries": [25, 50, 90],
-      "horizontalBoundaries": [90]
-    }
   }
 }
 ```
 
-### Transport
+###### Click trigger (`"on": "click"`)
+Use this configuration to fire a request when a specified element is clicked. Use `selector` to control which elements will cause this request to fire:
+  - `selector` A CSS selector used to refine which elements should be tracked. Use value `*` to track all elements.
+
+    ```javascript
+    "triggers": {
+      "anchorClicks": {
+        "on": "click",
+        "selector": "a",
+        "request": "event",
+        "vars": {
+          "eventId": 128
+        }
+      }
+    }
+    ```
+
+###### Scroll trigger (`"on": "scroll"`)
+Use this configuration to fire a request under certain conditions when the page is scrolled. Use `scrollSpec` to control when this will fire:
+  - `scrollSpec` This object can contain `verticalBoundaries` and `horizontalBoundaries`. At least one of the two properties is required for a scroll event to fire. The values for both of the properties should be arrays of numbers containing the boundaries on which a scroll event is generated. For instance, in the following code snippet, the scroll event will be fired when page is scrolled vertically by 25%, 50% and 90%. Additionally, the event will also fire when the page is horizontally scrolled to 90% of scroll width.
+
+
+    ```javascript
+    "triggers": {
+      "scrollPings": {
+        "on": "scroll",
+        "scrollSpec": {
+          "verticalBoundaries": [25, 50, 90],
+          "horizontalBoundaries": [90]
+        }
+      }
+    }
+    ```
+
+###### Timer trigger (`"on": "timer"`)
+Use this configuration to fire a request on a regular time interval. Use `timerSpec` to control when this will fire:
+  - `timerSpec` Specification for triggers of type `timer`. The timer will trigger immediately and then at a specified interval thereafter.
+    - `interval` Length of the timer interval, in seconds.
+    - `maxTimerLength` Maximum duration for which the timer will fire, in seconds.
+
+    ```javascript
+    "triggers": {
+      "pageTimer": {
+        "on": "timer",
+        "timerSpec": {
+          "interval": 10,
+          "maxTimerLength": 600
+        },
+        "request": "pagetime"
+      }
+    }
+    ```
+
+##### Transport
 The `transport` attribute specifies how to send a request. The value is an object with fields that
 indicate which transport methods are acceptable.
 
@@ -196,7 +226,14 @@ indicate which transport methods are acceptable.
      request, with credentials, and an empty body.
   - `image` Indicates the request can be sent by generating an `Image` tag. This will send a GET request.
 
-If more than one of the above transport methods are enabled, the precedence is `beacon` > `xhrpost` > `image`.
-If the client's user agent does not support a method, the next highest precedence method enabled will be used.
-By default, all three methods above are enabled.
+If more than one of the above transport methods are enabled, the precedence is `beacon` > `xhrpost` > `image`. Only one transport method will be used, and it will be the highest precedence one that is permitted and available. If the client's user agent does not support a method, the next highest precedence method enabled will be used. By default, all three methods above are enabled.
+
+In the example below, `beacon` and `xhrpost` are set to `false`, so they will not be used even though they have higher precedence than `image`. `image` would be set `true` by default, but it is explicitly declared here. If the client's user agent supports the `image` method, then it will be used; otherwise, no request would be sent.
 
+```javascript
+'transport': {
+  'beacon': false,
+  'xhrpost': false,
+  'image': true
+}
+```