Identify Api

Herogi CDP provides Identify API to collect your users data. To able to use segments and other campaign features fully you need to start sending your users metadata to Herogi.

Before we discuss how to send/collect user data let’s take a close look what type of attributes available on Herogi User entity

User Object

Your customer’s data defined as User within Herogi and each User has multiple core attributes and some custom attributes.

User Attributes

User Attributes is essentially key/value pair of data associated with any User object. All these attributes become available in Campaign / Complex Scenario context which gives you huge personalization capabilities. So it’s important to send as much as data possible to benefit from power features.

Attributes	Data Type	Required	Example	Description
hgid	STRING	NO	6ef91c7c-3363-4agh-1b0c-10e2tb537b71	Internal Herogi identifier, if you want to update use set, if you don’t provide it’ll generate one
externalUserId	STRING	NO	user123	[Unique] External user identifier such user id in your system or email, if you know it attach it so that you can associate your users in Herogi easily
email	STRING	NO	john@example.com	Email address of user, email campaigns will use this
mobileNo	STRING	NO	+901111111111	Mobile phone number of user, sms campaigns will use this
firsname	STRING	NO	John	Firstname of user
lastname	STRING	NO	Wick	Lastname of user
gender	STRING	NO	MALE	Gender of user. Available Options: MALE, FEMALE, OTHER
language	STRING	NO	EN	Language of user. ISO Alpha 2 Code
country	STRING	NO	US	Country of user. ISO Alpha 2 Code
city	STRING	NO	Wick	City of user
currentLocation	STRING	NO	”{"latitude":12.1218024,"longitude":100.3194508}”	Coordinates of user, this can be useful in location sensitive campaigns
timezone	STRING	NO	America/New_York	User timezone, this can be used timing campaigns properly, E.g send a push message in user’s timezone 3pm
facebookId	STRING	NO	12345678	Facebook identifier
twitterId	STRING	NO	elonmusk	Twitter username
lineId	STRING	NO	a123456	Line username
customAttributes	STRING	NO	”{"weddingBudget": ["LUXURY”, "PREMIUM"], ..}”	JSON string of custom attributes, this will be only stored if it’s created on Audience Dashboard first
emailOptin	STRING	NO	OPTIN	User grant for email. Available Options: OPTIN, OPTOUT. Default value is OPTIN
smsOptin	STRING	NO	OPTIN	User grant for sms. Available Options: OPTIN, OPTOUT. Default value is OPTIN
pushOptin	STRING	NO	OPTIN	User grant for push. Available Options: OPTIN, OPTOUT. Default value is OPTIN
webPushOptin	STRING	NO	OPTIN	User grant for webpush notification. Available Options: OPTIN, OPTOUT. Default value is OPTIN
locationOptin	STRING	NO	OPTIN	User grant for location sensitive op. Available Options: OPTIN, OPTOUT. Default value is OPTIN

Create/Update User

There are multiple ways of managing users. If you’re using a backend application and you want to manage how and when to add users then better to use our Rest api to connect. Alternative way is you can use our javascript library and add your web application which collects all this automatically with minimal effort.

Base URL

All URLs referenced in the documentation have the following base;

https://stream.herogi.com

Javascript SDK: herogi.min.js

Add first minimized js file to your website.

<head>
   ..
   ..
   <script src="https://client-sdk.s3.us-west-1.amazonaws.com/herogi.min.js"></script>
</head>

This will enable herogi object in the javascript scope which you can access and use

Now let’s identify users;


//Get your app id and app secret from Herogi Dashboard
//If you want to collect user location set third parameter true, this will ask user in browser to allow location data
herogi.init("APPID","APPSECRET", true);

//If you don't know anything about user you can create initial empty user like this, it will create hgid and persist in browser which later identify just updates
herogi.identify(null, null,null, function (res, d) {
        console.log(res);
        console.log(d);
    });

You can also set user attributes, custom user attributes and preferences when you call herogi.identify, here is an example;

herogi.identify(
  {"firtname" : "John", "lastname" : "Wick"}, 
  {"weddingBudget" : ["LUXURY", "PREMIUM"}
  {"emailOptin" : "OPTIN"}, function (res, d) {
        console.log(res);
        console.log(d);
    });

Finally if you identify that user has an internal identifier in your system; you can explicity set it on Herogi, this is most of the time when you actually login a customer and you know who she is in your system

herogi.identify("user1234567" //User id or unique identifier from your system
  {"firtname" : "John", "lastname" : "Wick"}, 
  {"weddingBudget" : ["LUXURY", "PREMIUM"}
  {"emailOptin" : "OPTIN"}, function (res, d) {
        console.log(res);
        console.log(d);
    });

External identifier helps Herogi to associate your user with Herogi user, if there is an existing user defined on Herogi with same external id Herogi will merge this data with the other record on our database, local hgid stored in previous sessions will be overriden by existing hgid coming from database

herogi.identify Documentation

herogi.identify(externalId, userAttributes, customAttributes, preferences, callback)

If you skip externalId all parameters can shift to left by 1

herogi.identify(userAttributes, customAttributes, preferences, callback)

Param	Data Type	Required	Example	Description
externalId	STRING	NO	123456	Unique userid, email from your system
userAttributes	OBJECT	NO	{“GENDER” : “FEMALE”}	Key-value attribute objects
customAttributes	OBJECT	NO	{“key” : “val”}	Key-value custom attributes objects
preferences	OBJECT	NO	{“smsOptin” : “OPT-IN”}	Key-value preference objects
callback	FUNC	NO	function(status, err)	Callaback function to get result of identify operation

POST /v1/identify

curl --location --request POST 'https://stream.herogi.com/v1/identify' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic AUTHKEY' \
--data-raw '{       
        "city": "Bangkok",
        "mobileNo" : "+90111111111",
        "email": "johnwick@example.com",
        "firstname": "John",
        "lastname" : "Wick",
        "externalUserId" : "johnwick@example.com",
        "country" : "EN",
        "language" : "EN",
        "timezone" : "Europe/Moscow",
        "hgid" : "6ef91c7c-3363-4agh-1b0c-10e2tb537b71"
        
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://stream.herogi.com/v1/identify',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{       
    "city": "Bangkok",
        "mobileNo" : "+90111111111",
        "email": "johnwick@example.com",
        "firstname": "John",
        "lastname" : "Wick",
        "externalUserId" : "johnwick@example.com",
        "country" : "US",
        "language" : "EN",
        "timezone" : "Europe/Moscow",
        "hgid" : "6ef91c7c-3363-4agh-1b0c-10e2tb537b71"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic AUTHKEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'stream.herogi.com',
  'path': '/v1/identify',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Basic AUTHKEY'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({"city":"Bangkok","mobileNo":"+90111111111","email":"johnwick@example.com","firstname":"John","lastname":"Wick","externalUserId":"johnwick@example.com","country":"US","language":"EN","timezone":"Europe/Moscow","hgid":"6ef91c7c-3363-4agh-1b0c-10e2tb537b71"});

req.write(postData);

req.end();