Merge branch...

Merge branch '244355-add-javascript-example-on-how-we-could-track-ui-events-using-usagedata' into 'master'

JS client for increment_unique_users API

See merge request gitlab-org/gitlab!43084

app/assets/javascripts/api.js

@@ -64,6 +64,7 @@ const Api = {
   issuePath: '/api/:version/projects/:id/issues/:issue_iid',
   tagsPath: '/api/:version/projects/:id/repository/tags',
   freezePeriodsPath: '/api/:version/projects/:id/freeze_periods',
+  usageDataIncrementUniqueUsersPath: '/api/:version/usage_data/increment_unique_users',
 
   group(groupId, callback = () => {}) {
     const url = Api.buildUrl(Api.groupPath).replace(':id', groupId);
@@ -686,6 +687,19 @@ const Api = {
     return axios.post(url, freezePeriod);
   },
 
+  trackRedisHllUserEvent(event) {
+    if (!gon.features?.usageDataApi) {
+      return null;
+    }
+
+    const url = Api.buildUrl(this.usageDataIncrementUniqueUsersPath);
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+
+    return axios.post(url, { event }, { headers });
+  },
+
   buildUrl(url) {
     return joinPaths(gon.relative_url_root || '', url.replace(':version', gon.api_version));
   },

changelogs/unreleased/244355-add-javascript-example-on-how-we-could-track-ui-events-using-usage.yml

+---
+title: JS client for increment_unique_users API
+merge_request: 43084
+author:
+type: added

doc/development/telemetry/usage_ping.md

@@ -360,7 +360,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF
    | `event` | string | yes | The event name it should be tracked |
 
    Response
-
+w
    Return 200 if tracking failed for any reason.
 
    - `200` if event was tracked or any errors
@@ -368,6 +368,18 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF
    - `401 Unauthorized` if user is not authenticated
    - `403 Forbidden` for invalid CSRF token provided
 
+1. Track events using JavaScript/Vue API helper which calls the API above
+
+   Example usage for an existing event already defined in  [known events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events.yml):
+
+   Note that `usage_data_api` and `usage_data_#{event_name}` should be enabled in order to rack events using API.
+
+   ```javascript
+   import api from '~/api';
+
+   api.trackRedisHllUserEvent('my_already_defined_event_name'),
+   ```
+
 1. Track event using base module `Gitlab::UsageDataCounters::HLLRedisCounter.track_event(entity_id, event_name)`.
 
    Arguments:

lib/gitlab/gon_helper.rb

@@ -49,6 +49,7 @@ module Gitlab
       push_frontend_feature_flag(:snippets_edit_vue, default_enabled: true)
       push_frontend_feature_flag(:webperf_experiment, default_enabled: false)
       push_frontend_feature_flag(:snippets_binary_blob, default_enabled: false)
+      push_frontend_feature_flag(:usage_data_api, default_enabled: false)
 
       # Startup CSS feature is a special one as it can be enabled by means of cookies and params
       gon.push({ features: { 'startupCss' => use_startup_css? } }, true)

spec/frontend/api_spec.js

@@ -1152,4 +1152,44 @@ describe('Api', () => {
       });
     });
   });
+
+  describe('trackRedisHllUserEvent', () => {
+    const expectedUrl = `${dummyUrlRoot}/api/${dummyApiVersion}/usage_data/increment_unique_users`;
+
+    const event = 'dummy_event';
+    const postData = { event };
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+
+    describe('when usage data increment unique users is called with feature flag disabled', () => {
+      beforeEach(() => {
+        gon.features = { ...gon.features, usageDataApi: false };
+      });
+
+      it('returns null', () => {
+        jest.spyOn(axios, 'post');
+        mock.onPost(expectedUrl).replyOnce(httpStatus.OK, true);
+
+        expect(axios.post).toHaveBeenCalledTimes(0);
+        expect(Api.trackRedisHllUserEvent(event)).toEqual(null);
+      });
+    });
+
+    describe('when usage data increment unique users is called', () => {
+      beforeEach(() => {
+        gon.features = { ...gon.features, usageDataApi: true };
+      });
+
+      it('resolves the Promise', () => {
+        jest.spyOn(axios, 'post');
+        mock.onPost(expectedUrl, { event }).replyOnce(httpStatus.OK, true);
+
+        return Api.trackRedisHllUserEvent(event).then(({ data }) => {
+          expect(data).toEqual(true);
+          expect(axios.post).toHaveBeenCalledWith(expectedUrl, postData, { headers });
+        });
+      });
+    });
+  });
 });