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.
Updated 4 months ago