feat: clickstream SDK for WeChat Mini Program (#1)

.eslintrc.json

@@ -0,0 +1,36 @@
+{
+ "env": {
+ "browser": true,
+ "es6": true
+ },
+ "extends": [
+ "eslint:recommended",
+ "plugin:@typescript-eslint/recommended",
+ "prettier"
+ ],
+ "overrides": [],
+ "parserOptions": {
+ "ecmaVersion": "latest",
+ "sourceType": "module"
+ },
+ "plugins": [
+ "import"
+ ],
+ "rules": {
+ "eqeqeq": "warn",
+ "@typescript-eslint/no-explicit-any": "off",
+ "import/order": [
+ "error",
+ {
+ "groups": [
+ "builtin",
+ "external"
+ ],
+ "alphabetize": {
+ "order": "asc",
+ "caseInsensitive": true
+ }
+ }
+ ]
+ }
+}

.github/release.yml

@@ -0,0 +1,11 @@
+changelog:
+ categories:
+ - title: Feature
+ labels:
+ - enhancement
+ - title: Fix
+ labels:
+ - bug
+ - title: Other Changes
+ labels:
+ - "*"

.github/workflows/build.yml

@@ -0,0 +1,17 @@
+name: WeChat SDK Build
+
+on:
+ push:
+ branches: [ "main" ]
+ pull_request:
+ branches: [ "main" ]
+
+jobs:
+ code-build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ - name: Run build
+ run: |
+ npm i
+ npm run build

.github/workflows/code-lint.yml

@@ -0,0 +1,19 @@
+name: WeChat SDK Lint
+
+on:
+ push:
+ branches: [ "main" ]
+ pull_request:
+ branches: [ "main" ]
+
+jobs:
+ code-lint:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ - name: Run npm install
+ run: npm i
+ - name: Run code format
+ run: npm run format
+ - name: Run code lint
+ run: npm run lint

.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release next version
+on:
+ workflow_dispatch:
+ inputs:
+ release_tag:
+ description: 'Release Tag'
+ required: true
+ type: string
+env:
+ NEW_VERSION: ${{ github.event.inputs.release_tag }}
+jobs:
+ release:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ with:
+ ref: main
+ fetch-depth: 0
+ token: ${{ secrets.PROJECT_TOKEN }}
+ - name: Modify for next release
+ run: |
+ chmod +x release.sh
+ ./release.sh ${{ env.NEW_VERSION }}
+ npm i
+ git diff
+ git config user.name '${{ vars.USER_NAME }}'
+ git config user.email '${{ vars.USER_EMAIL }}'
+ git add .
+ git commit -m 'release: clickstream WeChat SDK ${{ env.NEW_VERSION }}'
+ git push
+ git tag v${{ env.NEW_VERSION }}
+ git push origin v${{ env.NEW_VERSION }}
+ - name: Prepare release file
+ run: |
+ npm i
+ npm run release
+ - name: Create GitHub release
+ uses: softprops/action-gh-release@v1
+ with:
+ name: "Clickstream WeChat ${{ env.NEW_VERSION }}"
+ files: |
+ dist/clickstream-wechat.min.js
+ dist/clickstream-wechat.min.js.map
+ tag_name: "v${{ env.NEW_VERSION }}"
+ prerelease: true
+ generate_release_notes: true

.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: WeChat SDK Test
+
+on:
+ push:
+ branches: [ "main" ]
+ pull_request:
+ branches: [ "main" ]
+
+jobs:
+ code-test:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ - name: Run test
+ run: |
+ npm i
+ npm run test
+ - name: Upload Test Report
+ uses: codecov/codecov-action@v3
+ with:
+ name: report
+ files: coverage/coverage-final.json

.github/workflows/title-lint.yml

@@ -0,0 +1,48 @@
+name: Commit Title Lint
+
+on:
+ pull_request:
+ branches: [ "main" ]
+
+jobs:
+ title-lint:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: amannn/[email protected]
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ with:
+ # Configure which types are allowed.
+ # Default: https://github.com/commitizen/conventional-commit-types
+ types: |
+ fix
+ feat
+ docs
+ style
+ refactor
+ perf
+ test
+ build
+ ci
+ chore
+ revert
+ release
+ # Configure that a scope must always be provided.
+ requireScope: false
+ # Configure additional validation for the subject based on a regex.
+ # This example ensures the subject doesn't start with an uppercase character.
+ subjectPattern: ^(?![A-Z]).+$
+ # If `subjectPattern` is configured, you can use this property to override
+ # the default error message that is shown when the pattern doesn't match.
+ # The variables `subject` and `title` can be used within the message.
+ subjectPatternError: |
+ The subject "{subject}" found in the pull request title "{title}"
+ didn't match the configured pattern. Please ensure that the subject
+ doesn't start with an uppercase character.
+ # For work-in-progress PRs you can typically use draft pull requests
+ # from Github. However, private repositories on the free plan don't have
+ # this option and therefore this action allows you to opt-in to using the
+ # special "[WIP]" prefix to indicate this state. This will avoid the
+ # validation of the PR title and the pull request checks remain pending.
+ # Note that a second check will be reported if this is enabled.
+ wip: true

.gitignore

@@ -0,0 +1,10 @@
+.DS_Store
+.idea/
+*.iml
+.vscode
+node_modules
+/dist
+/lib
+/coverage
+/src/config.ts
+

.prettierignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+package.json
+package-lock.json

.prettierrc.js

@@ -0,0 +1,7 @@
+module.exports = {
+ trailingComma: 'es5',
+ singleQuote: true,
+ useTabs: true,
+ tabWidth: 2,
+ arrowParens: 'avoid',
+};

README.md

@@ -1,17 +1,147 @@
-## My Project
+# AWS Solution Clickstream Analytics SDK for WeChat
 
-TODO: Fill this README out!
+## Introduction
 
-Be sure to:
+Clickstream WeChat Mini Program SDK is part of [Clickstream Analytics on AWS](https://github.com/awslabs/clickstream-analytics-on-aws), it helps WeChat Mini Program (WMP) owner collect user events on WMP easily. The SDK leverages WeChat Mini Program framework and APIs. We designed well architected events recording and publish mechanism to ensure the efficiency and reliability of the SDK. With events being recorded, AWS Clickstream solution can generate statistics and analysis of specific scenario data. We provide numerous preset commonly used event statistics for Clickstream solution users.
 
-* Change the title in this README
-* Edit your repository description on GitHub
+## Usage Guidance
+
+### Import the SDK
+
+Download SDK bundled *.js* file and add it to the WeChat Mini Program project.
+
+### Initialize the SDK
+The SDK should be initialized with necessary configurations before it can work with Clickstream Analytics solution. Take TypeScript mini program project for example, add following code snippet in the *app.ts* file **BEFORE** default `App()` method and fill in `appId` and `endpoint` values, which can be got from Clickstream web console after registering the app to a Clickstream Analytics data pipeline.
+
+```typescript
+import { ClickstreamAnalytics } from './clickstream-wechat';
+
+ClickstreamAnalytics.init({
+ appId: 'your appId',
+ endpoint: 'https://example.com/collect'
+});
+```
+
+In addition to the required configuration `appId` and `endpoint`, there are optional configuration properties used for customizing the SDK.
+
+| Property Name | Required | Default Value | Description |
+|------------------------| :------: |----------------------|------------------------------------------------------------------------------|
+| appId | yes | - | appId of the project in Clickstream Analytics control plane |
+| endpoint | yes | - | the ingestion server endpoint |
+| sendMode | no | *SendMode.Immediate* | options: *SendMode.Immediate*, *SendMode.Batch* |
+| sendEventsInterval | no | 5000 | interval (in milliseconds) of sending events, only works for batch send mode |
+| autoTrackAppStart | no | true | whether auto record app view event |
+| autoTrackAppEnd | no | true | whether auto record app hide event |
+| autoTrackPageShow | no | true | whether auto record page view event |
+| autoTrackUserEngagement | no | true | whether auto record user engagement |
+| autoTrackMPShare | no | false | whether auto record when user shares mini program |
+| autoTrackMPFavorite | no | false | whether auto record when user adds mini program to favorites |
+| debug | no | false | whether print out logs in the console |
+| authCookie | no | - | auth cookie for AWS application load balancer auth |
+| sessionTimeoutDuration | no | 1800000 | session timeout duration in millisecond |
+
+The SDK configurations can be updated after initialization by calling `configure()` method
+
+```typescript
+import { ClickstreamAnalytics, SendMode } from './clickstream-wechat';
+
+ClickstreamAnalytics.configure({
+ appId: 'your appId',
+ endpoint: 'https://example.com/collect',
+ sendMode: SendMode.Batch,
+ debug: true,
+ authCookie: 'auth cookie',
+ autoTrackPageShow: false
+});
+```
+
+### Use the SDK
+
+#### Add User Info
+
+```typescript
+// add or update user attributes
+ClickstreamAnalytics.setUserAttributes({
+ userName:"carl",
+ userAge: 22
+});
+
+// when user login
+ClickstreamAnalytics.setUserId("UserId");
+
+// when user logout
+ClickstreamAnalytics.setUserId(null);
+```
+
+Current login user's attributes will be cached in wxStorage.
+
+#### Record Event
+
+SDK user can call `ClickstreamAnalytics.record()` method to record custom event. The property `name` is required, while the property `attributes` and `items` are optional. `attributes` property is an object, `items` property is an array list of `item` type object.
+
+`item` type definition:
+
+| Property Name | Type | Required |
+| ------------- | ---------------- | :------: |
+| brand | string | no |
+| category | string | no |
+| category2 | string | no |
+| category3 | string | no |
+| category4 | string | no |
+| category5 | string | no |
+| creative_name | string | no |
+| creative_slot | string | no |
+| id | string | no |
+| location_id | string | no |
+| name | string | no |
+| price | string \| number | no |
+| quantity | number | no |
+
+Custom event record samples:
+
+```typescript
+ClickstreamAnalytics.record({ name: 'albumVisit' });
+ClickstreamAnalytics.record({
+ name: 'buttonClick',
+ attributes: { buttonName: 'confirm', itemNo: 12345, inStock: true },
+ items: [
+ {
+ id: 'p_123',
+ name: 'item_name',
+ price: 168.99
+ }
+ ]
+});
+```
+
+## How to integrate and test locally
+
+**Integrate**
+
+Clone this repository to local, execute the following script to generate `clickstream-wechat.js`, `clickstream-wechat.min.js` and corresponding `.map` files, which will be located in the project *dist* folder.
+```bash
+cd clickstream-wechat && npm run release
+```
+
+Copy the `clickstream-wechat.js` or `clickstream-wechat.min.js` with corresponding `.map` files into WeChat mini program project, then use it by
+```typescript
+import { ClickstreamAnalytics } from './clickstream-wechat';
+```
+or
+```typescript
+import { ClickstreamAnalytics } from './clickstream-wechat.min.js';
+```
+
+**Test**
+
+```bash
+npm run test
+```
 
 ## Security
 
 See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
 
 ## License
 
-This project is licensed under the Apache-2.0 License.
-
+This library is licensed under the [Apache 2.0 License](./LICENSE).