Integrating Customer Data with the Formilla JavaScript API

You can integrate contact data -named Contact Attributes by Formilla- about your logged-in customers such as User ID, email, first name, last name, phone and signed up date with your Formilla account by using our JavaScript API.

Formilla also lets you pass custom data -named Contact Custom Attributes– about your customers giving you the ability to track important properties about them such as the plan someone is on, how much money they had spent in the last month, among others.

This post will give you an overview and guide you on how to accomplish this integration.

Note: if you’re using Formilla with a Wix website, the Formilla JavaScript API is not supported.

Example of Contact and Custom Attributes:

On the following code snippet you can see an example of the contact and custom attributes.

(function () {
	var head = document.getElementsByTagName("head").item(0);
	var script = document.createElement("script");
	
	var src = (document.location.protocol == 'https:' 
		? 'https://www.formilla.com/scripts/feedback.js' 
		: 'http://www.formilla.com/scripts/feedback.js');
	
	script.setAttribute("type", "text/javascript"); 
	script.setAttribute("src", src); script.setAttribute("async", true);        

	var complete = false;
	
	script.onload = script.onreadystatechange = function () {
		if (!complete && (!this.readyState 
			|| this.readyState == 'loaded' 
			|| this.readyState == 'complete')) {
		    complete = true;
		    Formilla.guid = 'cscd537a-4a00-4007-ab78-c3f3b17a730a';
			
		    // Contact attributes
		    Formilla.contactAttributes = {
			UserId: "100",                       // Contact Id as string
			Email: "mikethompson@gmail.com",     // Contact email address
			FirstName: "Mike",                   // Contact first name
			LastName: "Thompson",                // Contact last name
			Phone: "343111685",                  // Contact phone
			SignedUp_date: 1523354400            // Signed up date as a unix timestamp
		    };

		    // Contact Custom Attributes
		    Formilla.contactCustomAttributes = {
			"Account Number": 15621,             // Number
			"Plan Name": "Premium",              // String
			"Average Purchased Monthly": 1647.9, // Decimal
			"Last Purchase_date": 1524757984,    // Date as a unix timestamp
			"Is Manager": true                   // Boolean
		    };
	
			
		    Formilla.loadWidgets();                
		}
	};

	head.appendChild(script);
})();

 

Once you have added the attributes, you will be able to view them by clicking Contacts from the left hand menu.new-contact

First things first: when using the JavaScript API, we highly recommend enabling Secure Mode to maintain the integrity of your data, and ensure that any calls to Formilla are coming from you, and not being impersonated by someone else.

Steps To Add Contact Attributes

  1. Ensure that you have the Formilla chat script installed manually on your website and you’re not using a Formilla plugin. In case you’re using a plugin, you will first need to deactivate/uninstall it from your platform’s admin (WordPress, Joomla, etc.) and then install the chat script manually instead.
  2. You can also find this script by going to Settings from the menu and then select Installation. You’ll see the chat script on the right-hand side of the page in the large text area.   
  3. Once you’ve manually installed the code script in your website, you should set your logged-in users data within it by using the Formilla.contactAttributes and Formilla.contactCustomAttributes objects as you can see in the script above.
  4. You can easily create new custom attributes by adding additional key/value pairs into the Formilla.contactCustomAttributes object where the key will be the attribute name and the value for the data you’ll track.  For example, if you wanted to capture the total number of purchases associated to a logged-in user:
Formilla.contactCustomAttributes = { 
   ... 
   "Number of Purchases": 10 
};

 

Note: it can take a few minutes for new contact attributes to appear in your Formilla account. Today you can create up to 100 Contact Custom Attributes in your Formilla account.

Remove a contact custom attribute value

In some cases, you might need to remove the value from a custom attribute for a logged-in user. You can do this by passing null as the custom attribute value. Check the following example:

Formilla.contactCustomAttributes = {
   ...
   "Number of Purchases": null
};

 

Note: keep in mind that you cannot create new custom attributes by setting them to null. This means, the null value can only be used if the custom attribute was already created before.

Key Points to Remember:

  • Custom Attributes Names:
    • The following special characters are not allowed: .$~`!@#%^&*{}|\'”
    • The custom attribute name cannot be longer than 150 characters.
    • If you want to create a date type custom attribute, you’ll need to always add the _date placeholder at the end of its name. For example: LastPurchase_date, SubscriptionEnd_date, Birth_date.
  • Custom Attributes Values:
    • Today we do support the following data types: string, integer, decimal, date (in unix timestamp) and boolean.
    • For date custom attributes, you need to pass the value in unix timestamp.
  • Once a Custom Attribute is created into your Formilla account, it is not possible to change its data type neither to delete it.

Unsubscribe a contact from receiving emails:

If you’re sending automatic emails (Edge Premium feature) to customers and you need to unsubscribe them from receiving new emails going forward, you can do that by including the IsUnsubscribed contact attribute in your Formilla code snippet as follows:

// Contact attributes
Formilla.contactAttributes = {
	UserId: "100",
	Email: "mikethompson@gmail.com",
	FirstName: "Mike",
	LastName: "Thompson",
	Phone: "343111685",
	SignedUp_date: 1523354400
	IsUnsubscribed: true	          // Boolean 
};

In the same way, in case you need to resubscribe a contact instead, simply pass IsUnsubscribed: false.

Note: you can also unsubscribe/resubscribe a contact manually from your Formilla account by going to Contacts from the left menu, then search and click the contact from the list. On the next page, you’ll see the Unsubscribe/Resubscribe link above the email address input.

How To Add Events:

What is an Event? An event is basically any activity that is performed on your website. This can include things like, product purchase, add to cart, click on specific page/product, among others.

If you then want to send any interesting activity performed by users in your app to Formilla, then the Events is the right way to go.

Let’s see an example!

Imagine you’d like to track each time a user completes a purchase on your store, then you can fire the following line of code after the logged-in user has finished purchasing:

Formilla.PostEvent("Purchased");

Notes about Events:

  • You can create up to 100 different events names in your Formilla account.
  • Event names cannot include the dollar sign: $
  • You can send unlimited event occurrences for your contacts.
  • It can take a few minutes for events to appear in your Formilla account.

You can pass custom data with events via Event Custom Attributes. Continuing with the example above, we might want to know what product the user purchased, the quantity and the total amount of the purchase. You can accomplish this as follows:

var eventCustomAttributes = {
    "Product": "Laptop Lenovo Y700",
    "Quantity": 1,
    "Total": 989.00
};

Formilla.PostEvent("Purchased", eventCustomAttributes);

 

You also have the ability to add a success and an error callback when posting events. This way, you can perform additional processing on your end based on the request result, if necessary.

var eventCustomAttributes = {
    "Product": "Laptop Lenovo Y700",
    "Quantity": 1,
    "Total": 989.00
};

var success = function() {
    console.log("FormillaPostEvent - Success");
    // ...
};

var error = function() {
    console.log("FormillaPostEvent - Error");
    // ...
};

Formilla.PostEvent("Purchased", eventCustomAttributes, success, error);

 

Finally, you can view the most recent Events for a specific contact in your Formilla account by going to Contacts in the left menu, then click a contact to view the details. On the next page, you’ll see the events in the right-rail under the Recent Activity -> Events section.

2-events

Traffic. Leads. Sales.

Learn PROVEN strategies to generate thousands of visitors that CONVERT. Plus, you'll learn 5-star customer service tactics along the way.

100% privacy. Unsubscribe any time.