add test and doc

extensions/amp-analytics/0.1/test/test-requests.js

@@ -95,6 +95,30 @@ describes.realWin('Requests', {amp: 1}, env => {
         expect(h2Spy).to.be.calledOnce;
       });
 
+      it('should respect trigger immediate', function* () {
+        const spy = sandbox.spy();
+        const r = {'baseUrl': 'r', 'maxDelay': 1};
+        const handler = new RequestHandler(ampdoc, r, preconnect, spy, false);
+        const expansionOptions = new ExpansionOptions({});
+        handler.send({'e': '1'}, {}, expansionOptions);
+        clock.tick(100);
+        handler.send({'e': '2'}, {'immediate': 'str'}, expansionOptions);
+        clock.tick(100);
+        handler.send({'e': '3'}, {'immediate': true}, expansionOptions);
+        yield macroTask();
+        expect(spy).to.be.calledOnce;
+        expect(spy.args[0][0]).to.equal('r?e=1&e=2&e=3');
+        spy.reset();
+        handler.send({'e': '4'}, {}, expansionOptions);
+        clock.tick(800);
+        yield macroTask();
+        expect(spy).to.not.be.called;
+        clock.tick(200);
+        yield macroTask();
+        expect(spy).to.be.calledOnce;
+        expect(spy.args[0][0]).to.equal('r?e=4');
+      });
+
       it('should batch multiple send', function* () {
         const spy = sandbox.spy();
         const r = {'baseUrl': 'r2', 'maxDelay': 1};

extensions/amp-analytics/amp-analytics.md

@@ -260,6 +260,7 @@ The `triggers` configuration object describes when an analytics request should b
   - `on` (required) The event to listen for. Valid values are `render-start`, `ini-load`, `click`, `scroll`, `timer`, `visible`, `hidden`, `user-error`, [`access-*`](../amp-access/amp-access-analytics.md), and [`video-*`](./amp-video-analytics.md)
   - `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.
+  - `immediate` can be specified to work with request that support batching behavior. Setting `immediate` to `true` can help to flush batched request queue with some certain trigger. In this case, it's possible to reduce the request pings number without losing important trigger events.
   - `selector` and `selectionMethod` can be specified for some triggers, such as `click` and `visible`. See [Element selector](#element-selector) for details.
   - `scrollSpec` (required when `on` is set to `scroll`) This configuration is used in conjunction with the `scroll` trigger. Please see below for details.
   - `timerSpec` (required when `on` is set to `timer`) This configuration is used in conjunction with the `timer` trigger. Please see below for details.