Integration Document
Code-less event tracking on Mobile has different challenges, like lack of concept of Screen & inability to natively add additional click listeners to element. For example, addEventListener
's closest counterpart in android is setOnClickListener
ie once the application sets a click listener, 3rd party code (sdk's) will have to fallback to intelligent hacks to accomplish click tracking.
Also parameters collected on event also varies to a large extent. This document tries to cover the proposed normalisation for mobile & how the same can be piped into existing UserIQ infrastructure.
Almost all meta data will be stored on mobile's backend as first reference. In-order to inter-operate with existing infrastructure of useriq, this document details various endpoints required for sharing data.
Note: REST conventions are used to describe the endpoint requirements. These very well could be exiting endpoints with existing naming conventions with minor or no changes.
Data exchange & SDK API's
Visitor data collected from js tags & Mobile SDK's
user_id
: visitor iduser_name
: visitor nameaccount_id
: CustomerAccount Idaccount_name
: CustomerAccount Nameuser_email
: email address of usersignup_date
: visitor signup_date
Android API
UserIQSDK.initWithBuilder(this, "API-KEY")
.setId("EMP124")
.setName("Sudhakar")
.setEmail("sudhakar@useriq.com")
.setAccountId("ACC01")
.setAccountName("Acme Corp")
.setSignupDate("04-Mar-2018")
// Additional params
.addParam("Location", "Bangalore")
.addParam("Location", "Bangalore")
// Terminate chaining by init'ing
.build()
iOS API
[[UserIQSDK sharedInstance] initWithAPIKey:@"<YOUR-API_KEY>"
userId:@"<User-Id>"
name:@"<Username>"
email:@"<Email>"
accountId:@"<AccountId>"
accountName:@"<Acme Corp>"
signupDate:@"<16-May-2017>"
andParameters:@{@"<var1>":@"<val1>",@"<var2>":@"<val2>"}];
### App creation
On the mobile side, customer doesn't have to pre-create app by keying in the details. Since we upload binary & auto-detect all attributes from binary, API is required for creation of app on UserIQ's side. Once the app is created on mobile.useriq.com, API call will be made to create a site on UserIQ backend.
Once a new app is created `POST /mobile/app` will be called to create new `site_id`, which will be stored along `app` on mobile backend.
> TODO: API endpoint required for app creation
```python
POST /mobile/app
PUT /mobile/app/:site_id
screen/feature API's
Equivalent of Page is Screen on the Mobile side. Screen can be created/updated/deleted in the mobile dashbord. API's are required to setup meta data which is required for metrics/analytics
TODO: API endpoint required for page/feature CRUD
POST /screen
PUT /screen/:pageId
DEL /screen/:pageId
POST /screen/:pageId/feature
PUT /screen/:pageId/feature/:featId
DEL /screen/:pageId/feature/:featId
Campaign management
InApp modal will be primary content that will be supported for campaign's on the mobile for Origami Phase-1. Campaign data including content, styling needs to be stored on the mobile.useriq.com 's backend, so that same can be sync'd to devices when devices comes online.
However, segmentation needs to be stored in useriq's current backend so that existing infra can be used to segment audiences. On the SDK, all the devices are connected back to sdk-server
by live websocket
connection. On every screen change, sdk emits SDKEvent
containing screenId, visitorId
back to sdk-server
. Internally sdk-server
will communicate with POST /check-features
to evaluate eligibility of visitor to start a campaign.
TODO: API for campaign & segment creation
/POST /campaign
/PUT /campaign/:campaignId
/DEL /campaign/:campaignId
/POST /segment/
/PUT /segment/:segmentId
/DEL /segment/:segmentId
Note: If Campaign itself doesnt have to be duplicated on useriq's side campaign update
API can be ignored.
Visitor events
SDKEvent's are currently designed to be streamed live via the websocket
interface back to sdk-server
, which also includes screen visits & feature clicks. This will be used for invoking /check_features
to check for campaigns in scope and also for streaming data onto the existing UserIQ's kafka pipe to the https://stream.useriq.com/visits/push endpoint.
Following is the structure of raw events collected on mobile SDK's
type Event {
type: 'AppEnter' || 'AppExit' || 'ScreenEnter' || 'ScreenExit' || 'Tap or Click',
screenId?: string,
elementId?: string, // Element clicked on the screen. Only for Tap or Click events.
visitor_id: string,
event_ts: string,
}
/POST https://stream.useriq.com/visits/push
Content-type: application/json
Payload Body:
{
"events": [
{
"type": "pageview", // event type (i.e. 'ScreenEnter' || 'Click')
"screenId": 123,
"featureId": 123,
"event_ts": 1527089906097, // millisecond precision Unix timestamp
"site_id": "1",
"uid": "john.smith@useriq.com", // userId
"cvars": {
"1": ["user_id", "john.smith@useriq.com"],
"2": ["user_name", "John Smith"],
... {remaining cvars}
},
"res": "1280x800" // Screen resolution
}
,
... ],
"site_id": "1",
"platform_type": "mobile"
}
Check features
Check features is the endpoint we use to check if a user is in scope to receive a campaign based on his customer data and the app/page/etc that he/she is currently on, and return back the data needed to show the campaign.
QA: /GET https://qa.useriq.com/check_features
Production: /GET https://secure2.useriq.com/check_features
Query string parameters for mobile:
platform_type=mobile
site_id: site ID of the user/app currently being used
app_id: the appId of the mobile_apps record the user is using
uid: userId of currently logged in user
visitor_id: UserIQ generated visitor_id of user
_cvars: { "1": ["user_id", "john.smith@useriq.com"], "2": ["user_name", "John Smith"], ...}
Comments
0 comments
Article is closed for comments.