feat: add preset traffic source attributes (#7)

Co-authored-by: xiaoweii <xiaoweii@amazom.com>

Author: zhu-xiaowei

README.md

@@ -113,22 +113,33 @@ user's attribute when it changes.
 
 1. Add global attributes when initializing the SDK
 
+	 The following example code shows how to add traffic source fields as global attributes when initializing the SDK.
    ```typescript
+   import { ClickstreamAnalytics, Attr } from '@aws/clickstream-react-native';
    ClickstreamAnalytics.init({
-      appId: "your appId",
-      endpoint: "https://example.com/collect",
+      appId: 'your appId',
+      endpoint: 'https://example.com/collect',
       globalAttributes:{
-        _traffic_source_medium: "Search engine",
-        _traffic_source_name: "Summer promotion",
-      }
+        [Attr.TRAFFIC_SOURCE_SOURCE]: 'amazon',
+        [Attr.TRAFFIC_SOURCE_MEDIUM]: 'cpc',
+        [Attr.TRAFFIC_SOURCE_CAMPAIGN]: 'summer_promotion',
+        [Attr.TRAFFIC_SOURCE_CAMPAIGN_ID]: 'summer_promotion_01',
+        [Attr.TRAFFIC_SOURCE_TERM]: 'running_shoes',
+        [Attr.TRAFFIC_SOURCE_CONTENT]: 'banner_ad_1',
+        [Attr.TRAFFIC_SOURCE_CLID]: 'amazon_ad_123',
+        [Attr.TRAFFIC_SOURCE_CLID_PLATFORM]: 'amazon_ads',
+   			[Attr.APP_INSTALL_CHANNEL]: 'amazon_store',
+      },
    });
    ```
 
 2. Add global attributes after initializing the SDK
 
    ``` typescript
+   import { ClickstreamAnalytics, Attr } from '@aws/clickstream-react-native';
+
    ClickstreamAnalytics.setGlobalAttributes({
-     _traffic_source_medium: "Search engine",
+     [Attr.TRAFFIC_SOURCE_MEDIUM]: "Search engine",
      level: 10,
    });
    ```
@@ -149,7 +160,7 @@ You can add the following code to log an event with an item.
 **Note: Only pipelines from version 1.1+ can handle items with custom attribute.**
 
 ```typescript
-import { ClickstreamAnalytics, Item } from '@aws/clickstream-react-native';
+import { ClickstreamAnalytics, Item, Attr } from '@aws/clickstream-react-native';
 
 const itemBook: Item = {
   id: '123',
@@ -161,7 +172,8 @@ const itemBook: Item = {
 ClickstreamAnalytics.record({
   name: 'view_item',
   attributes: {
-    currency: 'USD',
+    [Attr.VALUE]: 99,
+		[Attr.CURRENCY]: 'USD',
     event_category: 'recommended',
   },
   items: [itemBook],
@@ -181,13 +193,13 @@ code to record a screen view event with two attributes.
   on the hashcode of the current Activity or ViewController.
 
 ```typescript
-import { ClickstreamAnalytics } from '@aws/clickstream-react-native';
+import { ClickstreamAnalytics, Attr, Event } from '@aws/clickstream-react-native';
 
 ClickstreamAnalytics.record({
-  name: ClickstreamAnalytics.Event.SCREEN_VIEW,
+  name: Event.SCREEN_VIEW,
   attributes: {
-    [ClickstreamAnalytics.Attr.SCREEN_NAME]: 'HomeComponet',
-    [ClickstreamAnalytics.Attr.SCREEN_UNIQUE_ID]: '123adf',
+    [Attr.SCREEN_NAME]: 'HomeComponet',
+    [Attr.SCREEN_UNIQUE_ID]: '123adf',
   },
 });
 ```

example/src/App.tsx

@@ -7,7 +7,12 @@ import {
   ScrollView,
   SafeAreaView,
 } from 'react-native';
-import { ClickstreamAnalytics, Item } from '@aws/clickstream-react-native';
+import {
+  ClickstreamAnalytics,
+  Item,
+  Attr,
+  Event,
+} from '@aws/clickstream-react-native';
 
 export default function App() {
   const initSDK = async () => {
@@ -20,7 +25,15 @@ export default function App() {
       isCompressEvents: false,
       sessionTimeoutDuration: 30000,
       globalAttributes: {
-        channel: 'Samsung',
+        [Attr.TRAFFIC_SOURCE_SOURCE]: 'amazon',
+        [Attr.TRAFFIC_SOURCE_MEDIUM]: 'cpc',
+        [Attr.TRAFFIC_SOURCE_CAMPAIGN]: 'summer_promotion',
+        [Attr.TRAFFIC_SOURCE_CAMPAIGN_ID]: 'summer_promotion_01',
+        [Attr.TRAFFIC_SOURCE_TERM]: 'running_shoes',
+        [Attr.TRAFFIC_SOURCE_CONTENT]: 'banner_ad_1',
+        [Attr.TRAFFIC_SOURCE_CLID]: 'amazon_ad_123',
+        [Attr.TRAFFIC_SOURCE_CLID_PLATFORM]: 'amazon_ads',
+        [Attr.APP_INSTALL_CHANNEL]: 'amazon_store',
         Class: 5,
         isTrue: true,
         Score: 24.32,
@@ -47,10 +60,10 @@ export default function App() {
 
   const recordCustomScreenViewEvents = () => {
     ClickstreamAnalytics.record({
-      name: ClickstreamAnalytics.Event.SCREEN_VIEW,
+      name: Event.SCREEN_VIEW,
       attributes: {
-        [ClickstreamAnalytics.Attr.SCREEN_NAME]: 'HomeComponent',
-        [ClickstreamAnalytics.Attr.SCREEN_UNIQUE_ID]: '123adf',
+        [Attr.SCREEN_NAME]: 'HomeComponent',
+        [Attr.SCREEN_UNIQUE_ID]: '123adf',
       },
     });
   };
@@ -68,8 +81,8 @@ export default function App() {
       name: 'product_view',
       attributes: {
         category: 'shoes',
-        currency: 'CNY',
-        price: 279.9,
+        [Attr.CURRENCY]: 'CNY',
+        [Attr.VALUE]: 279.9,
       },
       items: [item_shoes],
     });
@@ -93,7 +106,7 @@ export default function App() {
   const setGlobalAttributes = () => {
     ClickstreamAnalytics.setGlobalAttributes({});
     ClickstreamAnalytics.setGlobalAttributes({
-      channel: 'Samsung',
+      [Attr.APP_INSTALL_CHANNEL]: 'amazon_store',
       Class: 5,
       isTrue: true,
       Score: 24.32,

src/ClickstreamAnalytics.ts

@@ -105,10 +105,18 @@ export class ClickstreamAnalytics {
     return obj !== undefined && obj !== null && Object.keys(obj).length > 0;
   }
 
+  /**
+   * @deprecated The static object should not be used.
+   * please update to: `import { Event } from '@aws/clickstream-react-native'`.
+   */
   static readonly Event = {
     SCREEN_VIEW: '_screen_view',
   };
 
+  /**
+   * @deprecated The static object should not be used.
+   * please update to: `import { Attr } from '@aws/clickstream-react-native'`.
+   */
   static readonly Attr = {
     SCREEN_NAME: '_screen_name',
     SCREEN_UNIQUE_ID: '_screen_unique_id',

src/__tests__/ClickstreamAnalytics.test.ts

@@ -10,7 +10,7 @@
  *  OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
  *  and limitations under the License.
  */
-import { ClickstreamAnalytics } from '../index';
+import { ClickstreamAnalytics, Attr, Event } from '../index';
 import { NativeModules } from 'react-native';
 
 jest.mock('react-native', () => {
@@ -129,18 +129,18 @@ describe('ClickstreamAnalytics test', () => {
 
   test('test record custom screen view events', () => {
     ClickstreamAnalytics.record({
-      name: ClickstreamAnalytics.Event.SCREEN_VIEW,
+      name: Event.SCREEN_VIEW,
       attributes: {
-        [ClickstreamAnalytics.Attr.SCREEN_NAME]: 'HomeComponent',
-        [ClickstreamAnalytics.Attr.SCREEN_UNIQUE_ID]: '123adf',
+        [Attr.SCREEN_NAME]: 'HomeComponent',
+        [Attr.SCREEN_UNIQUE_ID]: '123adf',
       },
     });
     expect(NativeModules.ClickstreamReactNative.record).toHaveBeenCalledWith(
       expect.objectContaining({
-        name: ClickstreamAnalytics.Event.SCREEN_VIEW,
+        name: Event.SCREEN_VIEW,
         attributes: {
-          [ClickstreamAnalytics.Attr.SCREEN_NAME]: 'HomeComponent',
-          [ClickstreamAnalytics.Attr.SCREEN_UNIQUE_ID]: '123adf',
+          [Attr.SCREEN_NAME]: 'HomeComponent',
+          [Attr.SCREEN_UNIQUE_ID]: '123adf',
         },
       })
     );
@@ -207,6 +207,35 @@ describe('ClickstreamAnalytics test', () => {
     );
   });
 
+  test('test set traffic source in global attributes', () => {
+    ClickstreamAnalytics.setGlobalAttributes({
+      [Attr.TRAFFIC_SOURCE_SOURCE]: 'amazon',
+      [Attr.TRAFFIC_SOURCE_MEDIUM]: 'cpc',
+      [Attr.TRAFFIC_SOURCE_CAMPAIGN]: 'summer_promotion',
+      [Attr.TRAFFIC_SOURCE_CAMPAIGN_ID]: 'summer_promotion_01',
+      [Attr.TRAFFIC_SOURCE_TERM]: 'running_shoes',
+      [Attr.TRAFFIC_SOURCE_CONTENT]: 'banner_ad_1',
+      [Attr.TRAFFIC_SOURCE_CLID]: 'amazon_ad_123',
+      [Attr.TRAFFIC_SOURCE_CLID_PLATFORM]: 'amazon_ads',
+      [Attr.APP_INSTALL_CHANNEL]: 'amazon_store',
+    });
+    expect(
+      NativeModules.ClickstreamReactNative.setGlobalAttributes
+    ).toHaveBeenCalledWith(
+      expect.objectContaining({
+        [Attr.TRAFFIC_SOURCE_SOURCE]: 'amazon',
+        [Attr.TRAFFIC_SOURCE_MEDIUM]: 'cpc',
+        [Attr.TRAFFIC_SOURCE_CAMPAIGN]: 'summer_promotion',
+        [Attr.TRAFFIC_SOURCE_CAMPAIGN_ID]: 'summer_promotion_01',
+        [Attr.TRAFFIC_SOURCE_TERM]: 'running_shoes',
+        [Attr.TRAFFIC_SOURCE_CONTENT]: 'banner_ad_1',
+        [Attr.TRAFFIC_SOURCE_CLID]: 'amazon_ad_123',
+        [Attr.TRAFFIC_SOURCE_CLID_PLATFORM]: 'amazon_ads',
+        [Attr.APP_INSTALL_CHANNEL]: 'amazon_store',
+      })
+    );
+  });
+
   test('test set empty global attribute', () => {
     ClickstreamAnalytics.setGlobalAttributes({});
     expect(

src/index.ts

@@ -12,4 +12,4 @@
  */
 
 export { ClickstreamAnalytics } from './ClickstreamAnalytics';
-export { Item } from './types/Analytics';
+export { Item, Attr, Event } from './types/Analytics';

src/types/Analytics.ts

@@ -30,8 +30,42 @@ export interface Configuration {
   isTrackAppExceptionEvents?: boolean;
 }
 
+export enum Event {
+  SCREEN_VIEW = '_screen_view',
+}
+
+export enum Attr {
+  SCREEN_NAME = '_screen_name',
+  SCREEN_UNIQUE_ID = '_screen_unique_id',
+  TRAFFIC_SOURCE_SOURCE = '_traffic_source_source',
+  TRAFFIC_SOURCE_MEDIUM = '_traffic_source_medium',
+  TRAFFIC_SOURCE_CAMPAIGN = '_traffic_source_campaign',
+  TRAFFIC_SOURCE_CAMPAIGN_ID = '_traffic_source_campaign_id',
+  TRAFFIC_SOURCE_TERM = '_traffic_source_term',
+  TRAFFIC_SOURCE_CONTENT = '_traffic_source_content',
+  TRAFFIC_SOURCE_CLID = '_traffic_source_clid',
+  TRAFFIC_SOURCE_CLID_PLATFORM = '_traffic_source_clid_platform',
+  APP_INSTALL_CHANNEL = '_app_install_channel',
+  VALUE = '_value',
+  CURRENCY = '_currency',
+}
+
 export interface ClickstreamAttribute {
-  [key: string]: string | number | boolean;
+  [Attr.SCREEN_NAME]?: string;
+  [Attr.SCREEN_UNIQUE_ID]?: string;
+  [Attr.TRAFFIC_SOURCE_SOURCE]?: string;
+  [Attr.TRAFFIC_SOURCE_MEDIUM]?: string;
+  [Attr.TRAFFIC_SOURCE_CAMPAIGN]?: string;
+  [Attr.TRAFFIC_SOURCE_CAMPAIGN_ID]?: string;
+  [Attr.TRAFFIC_SOURCE_TERM]?: string;
+  [Attr.TRAFFIC_SOURCE_CONTENT]?: string;
+  [Attr.TRAFFIC_SOURCE_CLID]?: string;
+  [Attr.TRAFFIC_SOURCE_CLID_PLATFORM]?: string;
+  [Attr.APP_INSTALL_CHANNEL]?: string;
+  [Attr.VALUE]?: number;
+  [Attr.CURRENCY]?: string;
+
+  [key: string]: string | number | boolean | undefined;
 }
 
 export interface Item {