Android SDK

LivePinch provides a Android SDK that you can integrate with your android application, and with minimal effort start tracking user. LivePinch Android SDK provides following features.

  • Track users
  • Track any named application events
  • Track application launches, screen views, sessions, uninstallations and other user activity
  • Send push notifications and track user interactions with push notifications

Tracking Users

By default, Live Pinch tracks all users, and assigns a unique id to every user in order to identify a given user, it is important that you call login method onces a user logs in, and logout method when the user signs out.

Once login is called, All events, page views, clicks, sessions and actions are attributed to the logged in user, until a logout action is called.

Login method accepts a profile_key as an argument. See Profiles section for details on profile_key. Profile Key is a unique identifier for the user on your system, It could be an email, phone or profile_name any other unique identifier you identify the user with.

Profiles section describes the idea of profiles in detail. Profile Key section discusses, in detail, how profile keys are used with in Live Pinch system and how to effectively choose Profile Keys.

Obtaining LivePinch Instance

Start with obtaining an instance of LivePinch object. Here this refers to instance of your activity.

LivePinch lp = LivePinch.getInstance(this);

Obtaining LivePinch User Instance

To obtain a user instance

import com.livepinch.sdk.usertracking.LivePinchUser;

//...
LivePinchUser mLivePinchUser = LivePinch.getInstance(this).user();

Login/Logout

As described above, once you identify a given user with Profile Key in order to identify a user, you can either use the LivePinch instance as follows

lp.login(profile_key);

Alternatively, You can obtain instance of current user as follows, and call login method on the user object.

import com.livepinch.sdk.usertracking.LivePinchUser;

//...
LivePinchUser mLivePinchUser = lp.user();
mLivePinchUser.login(profile_key);

Profile Key document discusses on importance of choosing correct profile keys and ideal candidates for profile keys. The profile_key needs to be of type string. If you’re integer keys, be sure to call .toString() method to cast it to string before calling login.

The usual places to call above method are

  • User signup
  • User login

the identifier provided above remains unchanged until ‘logged out’ method is called.

Logout

Logout must be called when the user logs out of your system or his session times out. When a logout is called. A new anonymous user is created and returning user is tracked under this anonymous Id.

In order to logout, you can either call logout on LivePinch instance or on the LivePinch User Instance object directly

lp.logout();

Or, alternatively

lp.user().logout();

Set User Attributes

You can set arbitrary attributes for a given profile. See Profiles section for details on the attributes.

There primarily two ways of setting attributes

  • Set attributes as HashMap with String keys and one of the allowed values(String,Boolean,Date,Number)
  • Acquire the attribute builder object build the attributes by chaining serveral calls

Both methods are accessible both on Live Pinch Instance and on Live Pinch User Instance. These are discussed in following passages.

Using Hash Map

HashMap<String,Object> userAttributes = new HashMap<>();

// system attributes
userAttributes.put("email", "john.doe@gmail.com");
userAttributes.put("dob", "1959-09-26");
userAttributes.put("phone", "+919981332099");

// custom attributes
userAttributes.put("membership_level", "GOLD");
userAttributes.put("purchase_value", 25.5);
userAttributes.put("is_returning_user", true);

// either directly on livepinch instance
lp.setAttributes(userAttributes);

// OR livepinch user instance
mLivePinchUser.setAttributes(userAttributes);

Using Attribute Builder

To obtain the builder instance

// On LivePinch Instance
lp.userAttributeBuilder();

// On LivePincUserInstance
lp.attributeBuilder();

with builder instance you can chain several calls, Builder also providers serveral convinience methods to set system attributes. See Profiles section for detailed discussion on system attributes.

Here is a way is an few examples to set attributes with attribute builder

// Set predefined system attributes
lp.userAttributeBuilder().
  setEmail("john.doe@gmail.com").
  setPhoneNumber("+91991332099").
  build();

// Mix this with setting custom attributes
lp.userAttributeBuilder().
  setEmail("john.doe@gmail.com").
  setPhoneNumber("+91991332099").
  set("Membership Level", "GOLD").
  set("Purchase Value", 25.5).
  build();


// Additionally provide a dictionary to update
// the attributes with
lp.userAttributeBuilder().
  setEmail("john.doe@gmail.com").
  setPhoneNumber("+91991332099").
  set("Membership Level", "GOLD").
  set("Purchase Value", 25.5).
  updateWithAttributes(hashMap).
  build();

// Setting Gender
lp.userAttributeBuilder().
  setGender(LivePinchUser.Gender.MALE).
  build();

Following are convinience methods to set system attributes. Detailed discussion or attributes and there types can be found at Profiles section.

  • setFirstName
  • setLastName
  • setEmail
  • setGender
  • setBirthDate
  • setCountry
  • setPhoneNumber
  • optforEmail
  • optforSMS

Tracking Events

Events are discussed in detail in the Events section. Please be sure to understand how events are tracked.

Track any custom event the user performs with track event, The first argument is a string, Must be the name of the event, Second attribute is an object containing any arbitrary set of attributes and values that can be associated with this event.

  • Track Event only by event name
LivePinch lp = LivePinch.getInstance(this);
lp.trackEvent("Product - Page Viewed");
  • Track Event along with attributes
HashMap<String,Object> data = new HashMap<>();

data.put("Product Id", 25355);
data.put("Product Category", "shoes");
data.put("Product Color", "red");

lp.trackEvent("Added to Cart", data);

Tracking Screen Views

You can manually track screens, or set up so, LivePinch automatically tracks screen views.

Automatic Tracking

LivePinchTracker mLivePinchTracker = LivePinch.getInstance(this).getTracker();
mLivePinchTracker.setAutoTrackingEnabled(true);

By doing this, every activity inside application are recorded automatically by activity names. But fragments will not be recorded by using auto tracking method. For that you have to use manual tracking.

Manual Tracking

You need to add following lines of codes to onStart() and onEnd()

import com.livepinch.sdk.analytics.LivePinchTracker;

LivePinchTracker mLivePinchTracker = LivePinch.getInstance(this).getTracker();

@Override
public void onStart() {
    super.onStart();
    mLivePinchTracker.startTrackingScreen(this,"MainActivity");
}

@Override
public void onStop() {
    super.onStop();
    mLivePinchTracker.stopTrackingScreen(this,"MainActivity");
}

Install Tracking

LivePinch sdk provides installation tracking. The following sections describe how to set this up. If you are not using other services to track installations, then, simply setting up the manifest file the following way will setup install tracking.

<receiver
android:name="com.livepinch.sdk.InstallTrackingReceiver"
android:exported="true"
android:permission="android.permission.INSTALL_PACKAGES">
  <intent-filter>
      <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

In case you’re using other services as well, you setup callbacks to trigger LivePinch install tracking from your installation callback receiver.

@Override
public void onReceive(Context context, Intent intent) {
 //.....

 LivePinch.getInstance(getApplicationContext()).
   setCampaignData(source, content, campaign, medium, keyword,term);

 //.....
}

Here, the source, content, campaign, medium,``keyword`` and term are UTM parameters you receive for installation.

Here is a complete Example

public class InstallTrackingReceiver extends BroadcastReceiver {
    public static final String KEY_UTM_SOURCE = "utm_source";
    public static final String KEY_UTM_CONTENT = "utm_content";
    public static final String KEY_UTM_CAMPAIGN = "utm_campaign";
    public static final String KEY_UTM_MEDIUM = "utm_medium";
    public static final String KEY_UTM_KEYWORD = "utm_keyword";
    public static final String KEY_UTM_TERM = "utm_term";


    @Override
    public void onReceive(Context context, Intent intent) {
        String referrer = intent.getStringExtra("referrer");
        Log.i("INSTALLTRACK","Refferer: "+referrer);

        String[] referrerParts = referrer.split("&");
        String utmSource = getData(KEY_UTM_SOURCE, referrerParts);
        String utmContent = getData(KEY_UTM_CONTENT, referrerParts);
        String utmCampaign = getData(KEY_UTM_CAMPAIGN, referrerParts);
        String utmMedium = getData(KEY_UTM_MEDIUM, referrerParts);
        String utmKeyword = getData(KEY_UTM_KEYWORD,referrerParts);
        String utmTerm = getData(KEY_UTM_TERM,referrerParts);


        //Api Call To update campaign source
        LivePinch.getInstance(getApplicationContext()).setCampaignData(utmSource, utmContent, utmCampaign, utmMedium, utmKeyword,utmTerm);
    }

    private String getData(String key, String[] allData) {
        for (String selected : allData)
            if (selected.contains(key)) {
                return selected.split("=")[1];
            }
        return "";
    }
}

Track User Location

Add following permissions to Android Manifest file like below:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Our sdk will start automatically tracking location once user allow these permissions.