npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@aws/clickstream-react-native

v0.2.0

Published

ClickstreamAnalytics React Native SDK

Downloads

90

Readme

AWS Solution Clickstream Analytics SDK for React Native

Introduction

Clickstream React Native SDK can help you easily collect and report events from React Native apps to AWS. This SDK is part of an AWS solution - Clickstream Analytics on AWS, which provisions data pipeline to ingest and process event data into AWS services such as Amazon S3, Redshift.

The SDK relies on the Clickstream Android SDK and Clickstream Swift SDK. Therefore, Clickstream React Native SDK also supports automatically collect common preset events and attributes (e.g., session start, first open). In addition, we've added easy-to-use APIs to simplify data collection in React Native apps.

Visit our Documentation site to learn more about Clickstream React Native SDK.

Platform Support

Android: Supports Android 4.1 (API level 16) and later.

iOS: Supports iOS 13 and later.

Integrate SDK

Include SDK

npm install @aws/clickstream-react-native

After complete, you need to install the pod dependencies for iOS:

cd ios && pod install

Initialize the SDK

Copy your configuration code from your clickstream solution web console, we recommended you add the code to your app's entry point like index.js, the configuration code should look like as follows. You can also manually add this code snippet and replace the values of appId and endpoint after you registered app to a data pipeline in the Clickstream Analytics solution web console.

// index.js

import { ClickstreamAnalytics } from '@aws/clickstream-react-native';

ClickstreamAnalytics.init({
  appId: 'your appId',
  endpoint: 'https://example.com/collect',
});

Your appId and endpoint are already set up in it.

Make sure you call ClickstreamAnalytics.init as early as possible in your application’s life-cycle. And make sure the SDK is initialized when calling other APIs.

Start using

Record event

Add the following code where you need to record events.

import { ClickstreamAnalytics } from '@aws/clickstream-react-native';

// record event with attributes
ClickstreamAnalytics.record({
  name: 'button_click',
  attributes: {
    event_category: 'shoes',
    currency: 'CNY',
    value: 279.9,
  },
});

// record event with name
ClickstreamAnalytics.record({ name: 'button_click' });

Login and logout

import { ClickstreamAnalytics } from '@aws/clickstream-react-native';

// when user login success.
ClickstreamAnalytics.setUserId("userId");

// when user logout
ClickstreamAnalytics.setUserId(null);

Add user attribute

import { ClickstreamAnalytics } from '@aws/clickstream-react-native';

ClickstreamAnalytics.setUserAttributes({
  userName: "carl",
  userAge: 22
});

When opening the Apps for the first time after integrating the SDK, you need to manually set the user attributes once, and current login user's attributes will be cached in disk, so the next time app open you don't need to set all user attributes again, of course you can use the same API ClickstreamAnalytics.setUserAttributes() to update the current user's attribute when it changes.

Add global attribute

  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.

    import { ClickstreamAnalytics, Attr } from '@aws/clickstream-react-native';
    ClickstreamAnalytics.init({
       appId: 'your appId',
       endpoint: 'https://example.com/collect',
       globalAttributes:{
         [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

    import { ClickstreamAnalytics, Attr } from '@aws/clickstream-react-native';
    
    ClickstreamAnalytics.setGlobalAttributes({
      [Attr.TRAFFIC_SOURCE_MEDIUM]: "Search engine",
      level: 10,
    });

It is recommended to set global attributes when initializing the SDK, global attributes will be included in all events that occur after it is set.

Delete global attribute

ClickstreamAnalytics.deleteGlobalAttributes(['level','_traffic_source_medium']);

Record event with items

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.

import { ClickstreamAnalytics, Item, Attr } from '@aws/clickstream-react-native';

const itemBook: Item = {
  id: '123',
  name: 'Nature',
  category: 'book',
  price: 99,
  book_publisher: "Nature Research",
};
ClickstreamAnalytics.record({
  name: 'view_item',
  attributes: {
    [Attr.VALUE]: 99,
		[Attr.CURRENCY]: 'USD',
    event_category: 'recommended',
  },
  items: [itemBook],
});

Record Screen View events manually

By default, SDK will automatically track the preset _screen_view event when Android Activity triggers onResume or iOS ViewController triggers viewDidAppear.

You can also manually record screen view events whether automatic screen view tracking is enabled, add the following code to record a screen view event with two attributes.

  • SCREEN_NAME Required. Your screen's name.
  • SCREEN_UNIQUE_ID Optional. Set the id of your Component. If you do not set, the SDK will set a default value based on the hashcode of the current Activity or ViewController.
import { ClickstreamAnalytics, Attr, Event } from '@aws/clickstream-react-native';

ClickstreamAnalytics.record({
  name: Event.SCREEN_VIEW,
  attributes: {
    [Attr.SCREEN_NAME]: 'HomeComponet',
    [Attr.SCREEN_UNIQUE_ID]: '123adf',
  },
});

Record screen views when using React Navigation

Here's an example of globally logging React Native screen view events when using React Navigation 6.x

For other version of React Navigation, you can refer to official documentation: Screen tracking for analytics.

Other configurations

In addition to the required appId and endpoint, you can configure other information to get more customized usage when initialing the SDK:

import { ClickstreamAnalytics } from '@aws/clickstream-react-native';

ClickstreamAnalytics.init({
  appId: 'your appId',
  endpoint: 'https://example.com/collect',
  isLogEvents: true,
  isCompressEvents: true,
  isTrackScreenViewEvents: false,
  isTrackUserEngagementEvents: true,
  isTrackAppExceptionEvents: true,
  sendEventsInterval: 15000,
  sessionTimeoutDuration: 1800000,
  authCookie: 'your auth cookie',
  globalAttributes: {
    _traffic_source_medium: 'Search engine',
  },
});

Here is an explanation of each property:

  • appId (Required): the app id of your project in solution web control.
  • endpoint (Required): the endpoint path you will upload the event to ingestion server.
  • isLogEvents: whether to print out event json for debugging, default is false.
  • isCompressEvents: whether to compress event content when uploading events, default is true.
  • sendEventsInterval: event sending interval millisecond, works only bath send mode, the default value is 5000
  • isTrackScreenViewEvents: whether auto record native screen view events, default is true
  • isTrackUserEngagementEvents: whether auto record user engagement events, default is true
  • isTrackAppExceptionEvents: whether auto record exception events of native apps, default is false
  • sendEventsInterval: event sending interval millisecond, the default value is 10000 (10s)
  • sessionTimeoutDuration: the duration for session timeout millisecond, default is 1800000 (30 minutes)
  • authCookie: your auth cookie for AWS application load balancer auth cookie.
  • globalAttributes: the global attributes when initializing the SDK.

Configuration update

You can update the default configuration after initializing the SDK, below are the additional configuration options you can customize.

import { ClickstreamAnalytics } from '@aws/clickstream-react-native';

ClickstreamAnalytics.updateConfigure({
  appId: 'your appId',
  endpoint: 'https://example.com/collect',
  isLogEvents: true,
  authCookie: 'your auth cookie',
  isCompressEvents: true,
  isTrackPageViewEvents: false,
  isTrackUserEngagementEvents: false,
  isTrackAppExceptionEvents: false,
});

Logging events json in debug mode

import { ClickstreamAnalytics } from '@aws/clickstream-react-native';

ClickstreamAnalytics.init({
  appId: 'your appId',
  endpoint: 'https://example.com/collect',
  isLogEvents: true,
});

After configuring isLogEvents:true when initializing the SDK, when you record an event, you can see the event raw json in AndroidStudio Logcat or Xcode debug console by filter EventRecorder.

Disable SDK

You can disable the SDK in the scenario you need. After disabling the SDK, the SDK will not handle the logging and sending of any events. Of course, you can enable the SDK when you need to continue logging events.

import { ClickstreamAnalytics } from '@aws/clickstream-react-native';

// disable SDK
ClickstreamAnalytics.disable();

// enable SDK
ClickstreamAnalytics.enable();

How to integrate and test locally

Clone this repository locally and execute the following script to generate aws-clickstream-react-native-0.2.0.tgz zip package, which will be located in the project root folder.

cd clickstream-react-native && yarn && yarn run pack

Copy the aws-clickstream-react-native-0.2.0.tgz into your project, then execute the script in your project root folder to install the SDK.

yarn add ./aws-clickstream-react-native-0.2.0.tgz

Note: Please correct the SDK version and change the path to where the aws-clickstream-react-native-0.2.0.tgz file is located.

You can also find the aws-clickstream-react-native-0.2.0.tgz file in the Release page.

Test

yarn run test

Security

See CONTRIBUTING for more information.

License

This library is licensed under the Apache 2.0 License.