logo

Connecto – Personalization API Specification

This document will provide you the details of each of our APIs. If you are looking for a getting started document, here it is.

What is Real Time Events Tracking and How does it help ?

With Connecto you can create a profile for every visitor coming on your site or app. You can track any activity that you deem important for profiling users and along with the actions, Connecto will capture the Referral, Browser, Device, Device Size etc. to enrich the data. This profile information is then available to you to personalize the offers and messaging for each and every visitor coming on your site. So let’s dig in.

Jump right to a topic:

API Calls

Currently, we have 3 API calls:

  • Identify – To know who is the customer.
  • Track – To know what they are doing on your site/app.
  • Add Property – To add a property to user profile.

These calls are uniform for every website and app and do not have any dependency on platform. You need to exactly call these API’s in the form described below to send data to Connecto’s server. Once we have the profile data, the system will allow you to intelligently target your visitors in real time. Let us go through each of them across all platforms.

Web API

Identify:

The “identify” API call ties a customer to some identifiable information we already have about them. This identifiable information could be Name, Email, Phone, Device, etc. Calling Connecto’s method identify will be the first step towards the personalization in your website and app.

Here is an example of basic identify call that you need to make.

Identify Function Call
_connecto.identify(userId, traits);

which will looks like:

_connecto.identify(‘ABCD1234’, {
‘name’: ‘ABCD’,
’email’: ‘abcd@connecto.io‘,
‘phone’: +91-8888888888,
‘age’: ’28’,
‘DOB’: ’01-01-1999′
}
);

You need to make _connecto.identify call with a few parameters that is userId and traits. The identify call specifies a customer’s identity that you can refer across the lifetime of the customer. Thus, every identify call needs to be called with a unique identifier that could be UserId or email.

  • UserId: (String) A unique string identifier which could be your database Id or user email id etc. We would strongly recommend you to use Database Id for unique identifications as it will never change as oppose to Email Id etc. Thus, this unique Id will be consistent throughout the customer’s lifetime and will help us to identify him anyhow even if he changes name or email id. You can send username and email id as traits as discussed below. We will even maintain a profile for the non-identified users. These are the users who have never logged in or signed up or bought anything. We will give an anonymous Id to these users (generated from UUID and will be unique) and build their profile as well.
  • Traits: (Object) Traits are piece of information you wish to send with every user like email, name, phone, age, birthday etc. All these information will be used to build rich user profile and hence allow you to smartly segment and target them. This is just a JSON object or simply a dictionary  that you can send with each identify call for providing more user information. If you do not want to share any personal contact information, you can leave it and just call _connect.identify(‘ABCD1234’); Also, arrays and objects are currently not supported as trait values.
Track:

The “track” API call gives you an opportunity to capture any user action that is performed by user at your website or app along with its properties . Each action can be associated to an event like “Signed Up” or “Added to Cart” with some properties that give a better description of event like {“Plan” : “Basic”} or {“Category”: 4 for 499}.

Here is an example of basic track call that you need to make.

Track Function Call
_connecto.track(eventName, eventProperties);

which will looks like:

_connecto.track(Signed Up, {
‘Plan’: ‘Basic’,
‘accountType’: ‘Facebook’,
}
);

You need to make _connecto.track call with a few parameters that is event name and event properties. You can use the track calls to register all the actions that the user is performing on your site.

  • Event Name:(String) Every track call registers a unique user action or event. We strongly recommend you to keep the events name a little explanatory like “Added to Cart” or “Clicked Registration Button” etc. for uniqueness and your convenience. Do not name them like “Event 1” or “Event 2” etc. as it will be pretty confusing and uniqueness will also be hard to maintain.
  • Properties:(Object) Properties are piece of information that you can tie with every user action or event call. This can simply be a JSON object or dictionary that you can send with each track call. We recommend you to send as many properties as you want with each track call to get a more holistic picture about user actions in the end. Also, arrays and objects are currently not supported as trait values.

If you wish to know the userId for a particular user, you can simply call this function in browser console:

_connecto.getIdentity();

This will return the userId which will be “USER_ID” for our example. This will return userId if the user is already identified else will return the anonymousId assigned by Connecto.

Android API

Build:

To include Connecto’s Android SDK in your application, you need to point a dependency on

Connecto’s maven repo and include our SDK in your app’s dependencies as follows:
repositories {mavenCentral()maven { url ‘http://www.connecto.io/maven-repo’ }}
dependencies {
compile ‘io.connecto:connecto-android-sdk:0.0.2’
}

Specifying writeKey:

We also need the writeKey of your project to be specified in the resources files. In your projects’s res/values/ add a new “Values resource file”, with the following value

<?xml version=”1.0″ encoding=”utf-8″ ?><resources><!–Required, your Connecto project write key–><string name=”connecto_write_key”>XXXXX</string>
</resources>

Including Connecto in your activity:

import io.connecto.android.sdk.Connecto;import io.connecto.android.sdk.Traits;import io.connecto.android.sdk.Properties;

Identify:

Identify Call
connecto = Connecto.with(YourActivity.this);
connecto.identify(“Random User”, new Traits().putValue(“name”, “ABC”));

  • The first parameter is the unique ID by which this user should be identified.
  • The second parameter is the Traits object, which is essentially a Map<String, Object>
Track:

Track Call
connecto = Connecto.with(YourActivity.this);
connecto.track(“Add to Cart”, new Properties().putValue(“value”, 800));

  • The first parameter is the event name passed as a String
  • The second parameter is the Properties object, which is essentially a Map<String, Object>

3 found this helpful