Java

You can collect user attributes and events on your site using the Engage Java SDK. You can then utilize this to create user segments for analytics, broadcast messaging, and automation messages in Engage.

Don't Have an account? Create an Engage account.

Installation

Download engage-java.jar and add the jar file as a Module to your Java project. Download from https://github.com/engage-so/engage-java/releases/tag/v1.1.0

On IntelliJ IDEA: File -> Project Structure -> Modules -> Dependencies Tab -> Add -> JARs or Directories -> Attach jar

On Netbeans: Project properties -> Libraries -> Compile -> ADD JAR/folder -> Add Jar

Configuration

Use your public and private keys to initialize the SDK. Your keys can be found in the settings section of your Engage dashboard (Settings -> Account).

EngageClient client = new EngageClient("key", "secret");

Identifying users

You only need a unique identifier that represents the user on your platform to track their events and attributes on Engage.

Create a user resource object and pass the above client to it.

UserResource userResource = new UserResource(client);

//create the data to identify the user
HashMap<String, Object> data = new HashMap<>(){{
    put("id","U424");
    put("email","[email protected]");
}};

JSONObject response = userResource.identify(data);

id represents the unique identifier for the user on your platform. It is the only required parameter. You can send any other attribute you want e.g. age, plan. Here are the standard ones we use internally on the user profile:

• first_name

• last_name

• email

• is_account

• number (with international dialling code without the +)

• created_at (represents when the user registered on your platform. If not added, Engage sets it to the current timestamp.)

Identifying as an Account

If you want to identify a user as an Account, you can add an is_account property and set it to true:

UserResource userResource = new UserResource(client);

//create the data to identify the user
HashMap<String, Object> data = new HashMap<>(){{
    put("id","U424");
    put("is_account",true);
    put("email","[email protected]");
}};

JSONObject response = userResource.identify(data);

You can convert between Customer and Account user types with the methods below.

This converts a Customer to an Account:

JSONObject response = userResource.convertToAccount("uid");

This converts an Account to a Customer:

JSONObject response = userResource.convertToCustomer("aid");

Update/add user attributes

If you need to add new attributes or update an existing attribute, you can use the addAttribute method.

long l = Long.parseLong("608514751443");

HashMap<String, Object> data = new HashMap<>(){{
    put("first_name","testing");
    put("number", l);
}};

JSONObject response = userResource.addAttribute("U424", data);

(You can also use identify to update or add new attributes.)

Tracking user events and actions

You can track user events and actions in a couple of ways.

Tracking an event with no value:

JSONObject response = userResource.track("U424", "purchase");

Tracking an event with a value:

HashMap<String, Object> data = new HashMap<>(){{
    put("event","new sign");
    put("value", true);
}};

JSONObject response = userResource.track("U424", data);

event is the event you want to track. value is the value of the event. This can be a string, number or boolean. There is an optional timestamp parameter. If not included, Engage uses the current timestamp. The timestamp value must be a valid date-time string.

If you need to track more properties with the event, you can track it this way:

HashMap<String, Object> data = new HashMap<>(){{
    put("event","new sign");
    put("properties", 
    HashMap<String, Object>(){{
            put("product","T123");
            put("currency", "USD");
            put("amount", 12.99);
        }};
    );
}};

Add user to an account

This adds a user to an account if it exists

JSONObject response = userResource.addToAccount(uid, aid, role)

Where

• user_id - The uid of the Customer you want to add to the Account.

• account_id - The uid of the Account you are adding the Customer to.

• role - The role of the Customer in the Account. This is optional.

Change a user's role in an account

This changes a user's role in an account

JSONObject response = userResource.changeUserRole(uid, aid, role)

Remove a user from an account

This removes a user from an account

JSONObject response = userResource.removeFromAccount(uid, aid);

Set New Client

Change the userResource client

userResource.setClient(new EngageClient("key", "secret"));