Running UserReport survey in native mobile applications (Beta)

UserReport is a product to get your users Feedback. Initially we were covering your Web users across desktop, mobile and tablet traffic. However many users using native apps and their opinion matters a lot. Therefore we are working hard to provide application developers a nice and easy way to interview their users.

While we are working on iOS and Android SDK we are opening-up API that allows to run UserReport interviews inside any native application. Using this API requires you to signup to UserReport Company Centric Beta that will allow you to centralize how you learn your audiences on different digital touchpoints. In new interface you will be able to create Media and specify its type to Android or iOS application.

Then your development team need to talk to our API to run survey. API is very straight forward and can be implemented on any platform.

There are three main API endpoints related to running interviews:

  • https://api.userreport.com/collect/v1/visit
  • https://api.userreport.com/collect/v1/invitation
  • https://api.userreport.com/collect/v1/visit+invitation

For simplicity lets omit common part in future reference and understand what is the main purpose of each endpoint:

  • /visit - register event that user launched an application
  • /invitation - asks UserReport should this user be invited to take part in survey
  • /visit+invitation - combined method that performs both operations

Before diving into request specification lets get an overview of general concepts. UserReport for applications works in same way as it works for websites - it builds report over interview responses and recognizes users across websites to build demographic profile or users using your application.

In a web world UserReport uses cookies to identify users across websites. In application world device-ID's are used to recognize users across applications. These device-ID’s are called IDFA (Identifier For Advertisers) on iOS devices and AAID (Android Advertising ID) on Android devices. 

Same identifiers are also used to quarantine users so they are not invited to survey again and again. We use same quarantine rules as described in this article.

In addition we allow to send additional user identifiers like email or its hash, facebookId if your application support authorization. They will be treated as additional markers to identify visitor profile or quarantine settings.

API methods /invitation and /visit+invitation will make a decision should current visitor be invited to participate in survey basing on three factors:

  • is survey activated or not
  • global and local quarantine attached to user identifiers sent in API request
  • invitation frequency settings set in UserReport

If API will decide to invite user it will return link to a web page which will render invitation to take part in survey. This link should be loaded to WebView component of your application. Invitation will be customized with your logo and color configured in UserReport. User will have opportunity to accept invitation and reject it. If user accepts it - survey will be loaded in same page so it is recommended to give enough space to WebView component on screen - preferable almost whole screen. When user ends the survey, closes it during participation or rejects invitation - we send corresponding events so application can capture them and hide WebView from the screen.

Now it's time to describe all implementation details.

API request format

All endpoints will accept same request body

{
  "user": {
    "idfa": "Apple's Id For Advertisers",
    "adid": "Android Advertisers Id",
    "email": "email of user if known",
    "emailMd5": "md5 hash of user's email if known",
    "emailSha1": "sha1 hash of user's email if known",
    "emailSha256": "sha256 hash of user's email if known",
"facebookId": "facebook ID if known" }, "media": { "mediaId": "parameter-prodided-by-userreport", #required "networkId": "parameter-prodided-by-userreport", #required "bundleId": "string" }, "device": { "type": "mobile or tablet", "brand": "device brand", "manufacturer": "device manufacturer", "model": "device model", "os": "OS", "osVersion": "OS version", "screenDpi": 801, "screenHeight": 3840, "screenWidth": 2160 }, "customization": { "hideCloseButton": true or false } }

As you see request body is broken into section.

  • user — pieces of information that identifies current user, at least one parameter required 
  • media — UserReport identifiers needed to recognize your application
  • device — Information about device used by user, required
  • customization — invitation and survey will not contain close button in top right corner, application developer should implement it himself. Invitation will have only Accept and Reject buttons only.

Response from API has a following format

{
  "invite": true or false,
  "invitationUrl": "https link to URL"
}

If API return invite: true URL from invitationUrl should be loaded to WebView. We recommend to keep WebView hidden until our page notify that invitation is fully rendered. Invitation page send following events to output:

  • invitation-rendered — invitation is rendered and WebView can be shown
  • survey-close — either user rejected invitation or completed survey, or closed survey during participated; WebView should be hidden after receiving this event. 

We also duplicate same events to iOS WKWebView notification channel if supported. Here is a code used on our side to send notification:

event = "invitation-rendered or survey-close" 
window.webkit.messageHandlers.notification.postMessage({ body: event });

Our recommendation on API usage is following:

  • send /visit request each time user launches application
  • send /invitation request each time user launches application after he spend 5 minutes in application in total

Audience measurement for Kits

If you are using Kits and would like to measure your in-app audiences in Kits - it needs to be implemented next to API communication. 

Here is HelpDesk article describing tracking pixel request that needs to be made: https://helpdesk.audiencereport.com/hc/en-us/articles/115002191963-In-app-tracking
 
You can find [tcode] for your app inside UserReport interface. Development team needs to add call of tracking pixel inside on every screen view. Every tracking pixel request will be counted as pageview in Kit
 
Tracking pixel call needs to happen with browser-like User-agent header. 
We advice to get default browser User agent string using one of suggested ways:

SDK plans

We are working on Android SDK and iOS SDK that will be responsible for running UserReport surveys and Audience measurement out of the box. Also we are looking into supporting Google Analytics integration. If you would like to participate in Beta test of SDK send us message to support@userreport.com. Don't hesitate to contact our support team if you need help on implementing API to run UserReport surveys in-app.

Attachments

Comments

Powered by Zendesk