✨ Amp audio analytics support (ampproject#23317)

* New analytics trigger event in amp-audio.js * Created test page * Analytics trigger event in play/pause action * Unit test for audio-play/audio-pause analytics event * Document the analytics support in amp-audio.md * Fix failed type-check * Removes analytics trigger in play() and pause() call * Changes audio-play analytics event listener from playing event to play event * Removes audio play/pause analytics event unit test * Removes analyticsEvent_ private method and inlines triggerAnalyticsEvent function * Updates amp-audio.md Updates that audio-play and audio-pause are the two analytics events supported now * Fixes prettier errors
riklund · Aug 23, 2019 · 128b699 · 128b699
1 parent d166c2b
commit 128b699
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 1 deletion.
diff --git a/extensions/amp-audio/0.1/amp-audio.js b/extensions/amp-audio/0.1/amp-audio.js
@@ -27,6 +27,7 @@ import {closestAncestorElementBySelector} from '../../../src/dom';
 import {dev, user} from '../../../src/log';
 import {getMode} from '../../../src/mode';
 import {listen} from '../../../src/event-helper';
+import {triggerAnalyticsEvent} from '../../../src/analytics';
 
 const TAG = 'amp-audio';
 
@@ -109,6 +110,13 @@ export class AmpAudio extends AMP.BaseElement {
     this.audio_ = audio;
 
     listen(this.audio_, 'playing', () => this.audioPlaying_());
+
+    listen(this.audio_, 'play', () =>
+      triggerAnalyticsEvent(this.element, 'audio-play')
+    );
+    listen(this.audio_, 'pause', () =>
+      triggerAnalyticsEvent(this.element, 'audio-pause')
+    );
   }
 
   /** @override */

diff --git a/extensions/amp-audio/amp-audio.md b/extensions/amp-audio/amp-audio.md
@@ -131,6 +131,40 @@ Example:
 </amp-audio>
 ```
 
+## Analytics
+AMP audio analytics gathers data about how users interact with audios in AMP documents. AMP audio extension issues analytics events during their lifecycle. These events can be reported through the analytics configuration using `audio-*` triggers. `audio-play` and `audio-pause` are the two analytics events supported now.
+
+See [the AMP Analytics component](../amp-analytics/amp-analytics.md) for details on *amp-analytics* configuration.
+
+
+### Audio play trigger (`"on": "audio-play"`)
+
+The `audio-play` trigger is fired when the audio begins playing from a user clicking play or from autoplay beginning or resuming. Use these configurations to fire a request for this event.
+
+```javascript
+"triggers": {
+  "audioPlay": {
+    "on": "audio-play",
+    "request": "event",
+    "selector": "#audio1"
+  }
+}
+```
+
+### Audio pause trigger (`"on": "audio-pause"`)
+
+The `audio-pause` trigger is fired when the audio stops playing from a user clicking pause, from autoplay pausing, or from the audio reaching the end. Use these configurations to fire a request for this event.
+
+```javascript
+"triggers": {
+  "audioPause": {
+    "on": "audio-pause",
+    "request": "event",
+    "selector": "#audio1"
+  }
+}
+```
+
 ## Validation
 
 See [amp-audio rules](https://github.com/ampproject/amphtml/blob/master/extensions/amp-audio/validator-amp-audio.protoascii) in the AMP validator specification.
diff --git a/test/manual/amp-audio.amp.html b/test/manual/amp-audio.amp.html
@@ -7,6 +7,7 @@
   <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
   <link href='https://fonts.googleapis.com/css?family=Questrial' rel='stylesheet' type='text/css'>
   <script async custom-element="amp-audio" src="https://cdn.ampproject.org/v0/amp-audio-0.1.js"></script>
+  <script async custom-element="amp-analytics" src="https://cdn.ampproject.org/v0/amp-analytics-0.1.js"></script>
   <style amp-custom>
     body {
       max-width: 527px;
@@ -24,9 +25,36 @@
 </head>
 <body>
   <h1>amp #0</h1>
-  <amp-audio width="500" controls>
+  <amp-audio id="audio1" width="500" controls>
     <source src="/examples/av/audio.mp3" type="audio/mpeg">
     Your browser does not support the audio tag.
   </amp-audio>
+  <amp-analytics>
+    <script type="application/json">
+      {
+        "requests": {
+          "event": "https://foo.com/event?type=${eventType}"
+        },
+        "triggers": {
+          "audioPlay": {
+            "on": "audio-play",
+            "request": "event",
+            "selector": "#audio1",
+            "vars": {
+              "eventType": "audio-play"
+            }
+          },
+          "audioPause": {
+            "on": "audio-pause",
+            "request": "event",
+            "selector": "#audio1",
+            "vars": {
+              "eventType": "audio-pause"
+            }
+          }
+        }
+      }
+      </script>
+  </amp-analytics>
 </body>
 </html>