diff --git a/extensions/amp-analytics/amp-analytics.md b/extensions/amp-analytics/amp-analytics.md index fb2e7d25e0bb..275b622c3ff4 100644 --- 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. --> -# `amp-analytics` +### `amp-analytics` Capture analytics data from an AMP document. -## Behavior +#### Behavior The `` 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 `` tag is clicked: ``` -## Attributes +#### 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: ``` ... ``` - - `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. ``` ``` 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 `` configuration object uses the following format: @@ -112,7 +113,7 @@ The `` 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 +} +```