Standard Event Tracking API

[chpapa]

Description

A standard event tracking API supporting PostgreSQL as data store.

Design

Client API Design

SkygearTracker(container: SkygearContainer)
SkygearTracker.prototype.track(eventName: string, properties: { [string]: number | string | boolean })

Sample Code

Construction of a tracker

import SkygearTracker from 'skygear-tracker';
// skygear is actually an instance of SkygearContainer
import skygear from 'skygear';

// To construct an instance of SkygearTracker
// Invoke the constructor with an instance of SkygearContainer
const skygearTracker = new SkygearTracker(skygear);
// You can use this skygearTracker throughout your app if you only work with a single
// SkygearContainer

Usage of a tracker

skygearTracker.track('Posted an item for sale', {
  currency: 'HKD',
  price: 20,
});

Expected behavior

In addition to the properties given by the caller, the tracker also gather information from the runtime environment and send them to the server.

Common columns

• _id: a server generated UUIDv4 id for the event
• _user_id: the user id of the user, in our case it is _user.id
• _received_at: the timestamp with timezone when the event is received by the server
• _tracked_at: the timestamp with timezone when the event is tracker by the caller
• _sent_at: the timestamp with timezone when the event is sent by the client
• _event_raw: the event name as given by the caller, e.g. Posted an item for sale
• _event_norm: the normalized event_name, e.g. posted_an_item_for_sale. This is same as the table name in the relational database
• _ips: the ip as seen by the server.

Web specific columns

• _page_path: the pathname of the url, e.g. /about
• _page_search: the querystring of the url, e.g. ?utm_campaign=easter-sale
• _page_url: the full url, e.g. https://www.example.com/about?utm_campaign=easter-sale
• _page_referrer: the value of document.referrer
• _utm_campaign: the utm_campagin in querystring, if any
• _utm_channel: the utm_channel in querystring, if any
• _user_agent: the value of navigator.userAgent

Mobile specific columns

• _app_id: CFBundleIdentifier or Application.getPackageName()
• _app_version: CFBundleShortVersionString or PackageInfo.versionName
• _app_build_number: CFBundleVersion or PackageInfo.versionCode
• _device_id: [[UIDevice currentDevice] identifierForVendor] or Settings.Secure.ANDROID_ID
• _device_manufacturer: "Apple" or Build.MANUFACTURER
• _device_model: utsname.machine or Build.MODEL
• _device_os: "ios" or "android"
• _device_os_version: [[UIDevice currentDevice] systemVersion] or Build.VERSION.RELEASE
• _device_carrier: [CTCarrier carrierName] or TelephonyManager.getNetworkOperatorName()
• _device_locales: A list of comma separated BCP47 tags, e.g. "en-US,ja-JP,zh-Hant-HK"
• _device_locale: The first item of _device_locales
• _device_timezone: [[NSTimeZone localTimeZone] name] or TimeZone.getDefault().getID()

Open Questions

Put a list of open questions here before a complete design / specification is decided

Related Issues

• Server Issues
• Client Issues
• Guides Issues

Progress Tracker

• [x] Specification Design Approval
• [ ] Write (code + tests + API docs) then get them merged. Put All PR there
  • [ ] Code
  • [ ] Minimal tests
  • [ ] Minimal API Docs
• [ ] Guides. Put All PR there
• [ ] Release
  • [ ] Update release notes
  • [ ] Release

Advice

• Specification Design Approval
  • Once you get LGTM from another Skygear Core Team Member, you can check this checkbox. And apply the "workflow/design-complete" label.
• Coding
  • Use as many PRs as you need. Write tests in the same or different PRs, as is convenient for you.
  • API doc should goes in the same PR with the code.
  • As each PR is merged, add a comment to this issue referencing the PRs.
  • When you are done with the code, apply the "workflow/code-complete" label.
• Guides
  • Write or modify guides and get them merged in https://github.com/skygeario/guides
  • When the PR of guides is merged, check this checkbox and apply the "workflow/guides-complete" label.

[chpapa]

@royuen I remember you have mention Oursky team have implemented similar plugins for numerous time. Can you take the lead to implement it when it's about the right time?

[chpapa]

@louischan-oursky FYI. The existing description and the notes on API design are just a brain dump of something I discussed with @royuen before. Feel free to overwrite it with what you would like to propose.

[chpapa]

@tensiuyan why you removed the WIP label? I think Louis is actually working on it...

[chpapa]

@rickmak @louischan-oursky so you two discussed and think the current spec is good? Shall we assume the specification are approved and it is design-complete already?

[rickmak]

No, none ping me for any discussion. I don't know who approval the design spec.

[louischan-oursky]

@rickmak the initial implementation of the plugin part is here ready for review. I am going to work on the three client (android, ios, javascript). Can you create three repositories for me?

[rickmak]

• https://github.com/SkygearIO/event_tracking-SDK-JS
• https://github.com/SkygearIO/event_tracking-SDK-iOS
• https://github.com/SkygearIO/event_tracking-SDK-Android

[chpapa]

Or use something like this? https://github.com/rudderlabs/rudder-server