MobileIQ Data integration

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 id
• user_name : visitor name
• account_id : CustomerAccount Id
• account_name : CustomerAccount Name
• user_email : email address of user
• signup_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"], ...}