diff --git a/README.md b/README.md index b753fdb..ebd786f 100644 --- a/README.md +++ b/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', }, }); ``` diff --git a/example/src/App.tsx b/example/src/App.tsx index bc27545..2546be8 100644 --- a/example/src/App.tsx +++ b/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, diff --git a/src/ClickstreamAnalytics.ts b/src/ClickstreamAnalytics.ts index d39f1e7..38d027a 100644 --- a/src/ClickstreamAnalytics.ts +++ b/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', diff --git a/src/__tests__/ClickstreamAnalytics.test.ts b/src/__tests__/ClickstreamAnalytics.test.ts index 2a965e5..3e62632 100644 --- a/src/__tests__/ClickstreamAnalytics.test.ts +++ b/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( diff --git a/src/index.ts b/src/index.ts index 6c44b3b..3eefed1 100644 --- a/src/index.ts +++ b/src/index.ts @@ -12,4 +12,4 @@ */ export { ClickstreamAnalytics } from './ClickstreamAnalytics'; -export { Item } from './types/Analytics'; +export { Item, Attr, Event } from './types/Analytics'; diff --git a/src/types/Analytics.ts b/src/types/Analytics.ts index 80eaac4..f59eba0 100644 --- a/src/types/Analytics.ts +++ b/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 {