Usage

In this section, we will cover how to record in-app events, change operating modes via the SDK.

Record In-App Events

An in-app event represents an event or action performed by the end user within your mobile app. LotaData's SDK enables you to define, tag, record, and analyze in-app events for your mobile users. Example of commonly tagged events are: “app launched”, “app moved to foreground”, “app moved to background”, “start button clicked", "game level complete", "transaction start", "payment complete", "packaged picked up", "delivery complete".

To tag an in-app event, you should call the corresponding record function.

    //Providing a tag representing an event
    mMomentsClient.recordEvent("launched");

    //Providing a tag associated to a numerical value
    mMomentsClient.recordEvent("purchase", 2.99);

    //Providing multiple tags representing an unique event
    List eventsList = Arrays.asList("event A", "event B", "event C");
    MomentsClient.recordEvent(eventsList);

    //Providing a map of tags, where each tag has a related object (text description, for example)
    Map<String, Object> eventsMap;
    eventsMap = new HashMap<String, Object>();
    eventsMap.put("user event", "the user is doing task A");
    eventsMap.put("system event", "the system is doing task B");
    mMomentsClient.recordEvent(eventsMap);

Change Tracking Modes

You can dynamically change the SDK tracking or operating mode. Note that any changes to the tracking mode will presist across app launches.

For example, when the app is in the foreground, you can reset the tracking mode to Route by making the below call.

    mMomentsClient.setFgTrackingMode(TrackingMode.Route);

Analogously, you can also reset the tracking mode when the app is in background, by making calls like below.

    mMomentsClient.setBgTrackingMode(TrackingMode.MINIMAL_POWER);

For more details about the tracking modes, please review the section on SDK Tracking Modes.

Get Location Events

Apps can personalize the experience with accurate geo-context and location events.

The SDK gets a location fix as soon as initialized and starts to save position history on the device as well in the cloud. The SDK provides real-time callbacks when the phone departs an area, arrives in an area, or stays within an area. You can also get callbacks when the phone moves a significant distance or stays in the same place for longer periods of time.

Each location event is accompanied by a string indicating the type of event recorded. There is no need for you to persist any data in your app, the SDK will do it all for you.

Event Description
arrival triggered when user arrives at a location
stay triggered when user stays at the same location
departure triggered when user leaves a location
move triggered when user moves a significant distance
ping periodic ping to get location and generate deeper insights
sys generated by the SDK to monitor init & transition events
tag generated by you, the user of our SDK


To register for and receive the location events, use the below code snippet:

    mMomentsClient.monitorLocation("anything", new LocationCallback<String>() {
        @Override
        public void handleLocation(String extra, Location loc) {
            Bundle bundle = loc.getExtras();
            String action = bundle.getString(Moments.KEY_TRAIL_ACTION);
            if(Moments.TRAIL_ACTION_DEPARTURE.equals(action)){
              bundle.getLong(Moments.KEY_ARRIVAL_TIME);
            }
            // Do something
        }
    });

Get Current Location

You can request a new location fix at any time with a requestLocation call. This call guarantees that the supplied location is no older than 60 seconds (default).

The returned location object will always include latitude, longitude, and timestamp. Additional geo-context fields can be verified with the isSet function.

    mMomentsClient.requestLocation("anything", new LocationCallback<String>() {
        @Override
        public void handleLocation(String extra, Location loc) {
            // Do something
        }
    });

If you do not need up to the minute freshness of location, you can also call bestKnownLocation which instantly returns the most recent location fix.

    //Note: May return null
    mMomentsClient.getBestKnownLocation();

Get Historical Data

We want you to access the historical location data and activity data for your mobile users. We would like you to customize and personalize your app experience based on location history and inferred user behaviors.

There are 3 ways of consuming historical data.

  • In-app calls to directly access history
  • JSON formatted data from our RESTful APIs
  • Deep insights and rich visuals in GeoDash

To check for new location data when your app relaunches you can check historySize and then call getHistoricalPosition(int).

Location history is a bounded LIFO queue limited to 1000 (default) entries. In other words, returned record 0 is the most recent and record 999 is the oldest.

  if(mMomentsClient.getHistorySize()>0){
    loc = mMomentsClient.getHistoricalPosition(0);
    yourThing.processLocation(loc);
  }

Know when Payload is sent

You can get a notification to be aware when a payload is sent to our backend. Just add the below code in you Activity:

    protected BroadcastReceiver receiver = null;
    protected Context mContext = null;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Do something
        mContext = this;
        registerReceiver();
    }

    protected void registerReceiver() {
        receiver = new BroadcastReceiver() {
            @Override
            public void onReceive(Context context, Intent intent) {
        // Do something
            }
        };

        LocalBroadcastManager.getInstance(this).registerReceiver((receiver),
                new IntentFilter(Moments.PAYLOAD_SENT)
        );
    }

    protected void onDestroy() {
        LocalBroadcastManager.getInstance(this).unregisterReceiver(receiver);
        // Do something
        super.onDestroy();
    }

Questions?

We are eager to hear from you and happy to share best practices for integrating the SDK. There are many ways for you to reach us:

But first, please sign up for an account with LotaData so that we may send you the link to download our SDK.


Was this helpful? Yes, thanks! Not really

results matching ""

    No results matching ""