Combining Installs, Updates and Opens

Previously, our Measurement API supported two actions: install and update, which in turn created separate install and update logs.

With the release of the TUNE SDK v3.0, we updated the Measurement API to support measure session to automatically handle the logic for app installs, updates, and opens. With measure session, we create the following logs:

  • Install – The first “app open” event that MAT logs for the user, regardless if the user is new or existing.
  • Update – The “app open” event when the SDK version, app version, or OS version changes from one open to the next.
  • Open – The opening of the app and app resume (when the app becomes active again).

 

When an install or update occurs, we persist two logs: the open log and the install or update log. This persistence allows us to make the (correct) assumption that every “app open” event has an open log, and gives us the ability to then determine if the action was an install or an update when processing the request.
Combining the multiple actions (install, update, open) into a single “session” action:

  • Simplifies implementing the logging of installs and opens
  • Enables 1:1 reconciling of installs and first app opens
  • Allows for simpler debugging and reconciliation with third parties/app stores
  • Measures opens used for retention analysis

Handle Existing Users

With the implementation of the measure session, you no longer need to make a different request to measure the update. But if your app already has existing users prior to implementing our SDK, what happens when you start notifying measure session for these existing users? (will existing users be counted as new installs?)

To handle existing users prior to implementing our SDK, you’ll need to use this parameter:

  • existing_user – Set to 1 (true) for users that are existing users; else set to 0. The default is 0 (false).

Setting existing_user=1 for existing users of your app prevents us from attributing those existing users to publishers and including them as newly acquired users in your reports.
Example measure session with existing user flag set:

//YOUR_ADVERTISER_ID.measure.mobileapptracking.com/serve?action=session&advertiser_id=877&sdk=server&package_name=app.atomic.dodgeball&ios_ifa=AAAAAA-BBBB-CCCC-11111-2222222222222&ios_ad_tracking_disabled=0&ios_ifv=ZZZZZZ-BBBB-CCCC-11111-2222222222222&user_id=10000000001&device_ip=123.123.123.123&device_brand=Apple&device_model=iPhone5,2&device_carrier=Verizon&country_code=US&existing_user=1&response_format=json

To lean more, refer to how to handle existing users prior to SDK implementation.

 

Measure Session Use Cases

To learn how the measure session handles installs, updates, and opens, review the following use cases.

Case 1

If this event is the first “app open” event that the Measurement API has seen for the user, then the Measurement API creates an open and install log.

  1. User clicks on ad and installs mobile app.
  2. User opens app for the first time.
  3. Client’s SDK / third-party code measures the open.
  4. Client notifies us of open via Measure Session endpoint.
    1. We create an install log because we don’t have a previous record of the user.
    2. We creates an open log.
    3. We attribute the install and open to the publisher of the click in Step 1.

Case 2

If this event is the first “app open” event that the Measurement API has seen for the user and existing_user is true, then the Measurement API creates an open and install log. Because we don’t have a previous install or update log, it cannot determine if the sdk_version or other parameters have changed required to create an update. The install is not attributed since by default existing users are not attributed.

  1. User clicks on ad and installs mobile app.
  2. User opens app for the first time.
  3. Client’s SDK / third-party code measures the open.
  4. Client notifies us of open via Measure Session endpoint with existing_user=1.
    1. We create an install log with existing_user=1 since it does not have a previous record of the user.
    2. We creates an open log.

Case 3

If the App Version, SDK Version, OS Version or Package Name changes from one “app open” to the next, then the Measurement API creates an update log.

  1. User clicks on an ad and installs mobile app.
  2. User opens app for the first time.
  3. Client’s SDK / third-party code measures the open.
  4. Client notifies us of open via Measure Session endpoint with app_version=1.1.
    1. We create an install log because we don’t not have a previous record of the user.
    2. We create an open log.
    3. We attribute the install and open to the publisher of the click in Step 1.
  5. User opens app several days later.
  6. Client’s SDK / third-party code measures the open.
  7. Client notifies us of open via Measure Session endpoint with app_version=1.2.
    1. Since the app version is different, we create an update log.
    2. We create an open log.

If we have a previous update log, then the Measurement API uses that log to compare the previous app_version and sdk_version to the current request, otherwise it uses the previous open log.  If the app_version or sdk_version changes from the last update or open, then the Measurement API creates an update log.

Have a Question? Please contact support@tune.com for technical support.