Enabling User Journey

Engine allows you to learn more about your user's journey. User Journey is the story of where a user goes throughout the day. For example:

  • The user started out at home.
  • From 9:15am - 9:30am the user drove from home to work at Factual.
  • From 9:30am - 12:30pm the user was stationary at work at Factual.
  • From 12:30pm - 12:35pm the user walked from Factual to Shake Shack at the Westfield Century City Mall.
  • etc.

There are two types of user journey callbacks in the SDK: events and spans.

Events are delivered when small updates in the user's state occur. You can get a user journey event when the user's activity changes (ex: from stationary to walking), when the user's visiting state changes (ex: ingresses at or egresses from somewhere), when the user's place attachment state changes (ex: the user is now visiting a Shake Shack, but was previously at Starbucks), or when their app state changes (ex: the user backgrounds or foregrounds the app).

Spans are summarized user journey information over a defined span of time. Spans don't overlap with each other. There are two types of spans: transit spans (the user was traveling from one location to another) and stationary spans (the user was stopped at a location). Spans bundle up all of the state changes you would get in user journey events into individual span objects.

Consider the following user journey events:

  • The user is at Shake Shack.
  • The user started driving at 4:00pm.
  • The user stopped driving and is now stationary at 4:30pm.
  • The user is at Starbucks at 4:30pm.

This would be summarized in a single user journey span:

  • From 4:00pm - 4:30pm the user drove from Shake Shack to Starbucks.

Track User Journey

To set up your app to receive user journey information, first create a class that extends UserJourneyReceiver. For example:

package com.factual.androidwalkthrough;

import android.content.Context;
import android.util.Log;

import com.factual.engine.api.mobile_state.UserJourneyEvent;
import com.factual.engine.api.mobile_state.UserJourneyReceiver;
import com.factual.engine.api.mobile_state.UserJourneySpan;

import org.json.JSONException;

public class ConsoleLoggingUserJourneyReceiver extends UserJourneyReceiver {
  @Override
  public void onContext(Context context) {
    // If you need fields from the context
  }

  @Override
  public void onUserJourneyEvent(UserJourneyEvent userJourneyEvent) {
    try {
      Log.i("engine", "Received User Journey event: " + userJourneyEvent.toJson().toString());
    } catch (JSONException e) {
      Log.e("engine", "Error with User Journey json");
    }
  }

  @Override
  public void onUserJourneySpan(UserJourneySpan userJourneySpan) {
    try {
      Log.i("engine", "Received User Journey span: " + userJourneySpan.toJson().toString());
    } catch (JSONException e) {
      Log.e("engine", "Error with User Journey span json");
    }
  }
}

Then add this receiver to your AndroidManifest.xml for example:

...
    <receiver android:name=".ConsoleLoggingFactualClientReceiver"/>
    <receiver android:name=".ConsoleLoggingUserJourneyReceiver"/>
  </application>
...

Finally, set the receiver after the SDK is initialized. For example:

@Override
  public void onInitialized() {
    try {
      FactualEngine.setUserJourneyReceiver(ConsoleLoggingUserJourneyReceiver.class);
      FactualEngine.start();
    } catch (FactualException e) {
      Log.e("engine", e.getMessage());
    }
  }

After these steps, your app will receive user journey event and span updates.