JavaScript Integration

JavaScript SDK will let you integrate with React, Meteor, AngularJS and more. Enter to see how to use widget methods, enable events etc.
Dashboard mockup

How to set it up?

Custom javascript methods let you achieve desired goals using only frontend actions. Methods listed below are available though a global window object UE. Depending on your use case, you can pass data inside User.com app in many ways. Using widget methods, you will be able to interact with user much closer updating his data within page hit, initializing widget with a new user or destroying the whole widget instance.

Then, you can move to widget callbacks to interact with chat widget easily. These methods let you trigger actions when specific scenario happens.

The last part, describes userengage method for sending events or updating user attributes.

Please note that this is a JavaScript API/SDK documentation, for the REST API please head to this url.

Remember, apiKey is required to use methods listed below.

Widget methods

UE.pageHit()

Within UE.pageHit() methods you can update the user with the same attributes as in window.civchat object (including custom attributes).

How does it work?

pageHit() sends a request to our server and updates a URL (generates new page view) and passed user attributes with certain data. It’s an equivalent of navigating to new page in "standard" HTTP installations.

Copied to clipboard!
<script>
  UE.pageHit({
    apiKey: 'YOUR_API_KEY',
    name: "John Doe",
    email: "myemail@example.org",
    gender: 2,
    status: 2,
    phone_number: "+48754123434", // Must be a valid E.164 format
    score: 0,
    company: {
      revenue: "$239.9 billion",
      employees: 32
    },
    source_context: {
      foo: "bar",
      john: "doe"
    }
  });
</script>

For some custom attributes data type, you have to pass data in a specific way:

- fixed type: { fixed_attr: "value1" } or { fixed_attr: ["value1"] }

- fixed type with allow multiple choice enabled: { fixed_attr: ["value1", "value2"] }

- datetime format: compatible with ISO 8601 format, e.i.: { datetime_attr: "2016-08-03 12:00:00+00:00" }

- date (YYYY-DD-MM): { date_attr: "2016-08-03" }

UE.resetAuth()

This function resets __ca__chat cookie, then creates a new one, which results in creating a new user. Parameter data is an object with the api key. Remember, it also resets a global cookie. You can use it to keep users privicy on the higher level. After user log out from your application, you can run this function and without loggin in, this user won’t be able to check conversations history on chat.

Copied to clipboard!
UE.resetAuth({
  apiKey: "YOUR_API_KEY"
});

You can also provide more information about the new user (ie. email address):

Copied to clipboard!
UE.resetAuth({
  apiKey: "YOUR_API_KEY",
  email: "johndoe@mydomain.com"
});

UE.destroy()

Destroy current widget instance and remove window from DOM. This method takes no arguments. After the current widget instance has been destroyed, you cannot refer to the ue methods.

Widget callbacks

After the window widget is loaded you can tigger a specific actions depending on the method you would like to use. The method invokes immediately. It makes sure that widget code has already finished executing. All of them are listed below.

onLoad()

Triggered when widget window is loaded.

Copied to clipboard!
UE.pageHit({
  apiKey: "YOUR_API_KEY",
  email: "johndoe@example.com",
  name: "John Doe",
  phone_number: "+48123456789",
  source_context: {
    foo: "bar",
    john: "doe"
  },
  onLoad() {
    alert("Widget loaded!");
  }
});

onMessage()

Triggered for every incoming message. Message object will be passed into triggered function.

Copied to clipboard!
UE.pageHit({
  apiKey: "YOUR_API_KEY",
  email: "johndoe@example.com",
  name: "John Doe",
  phone_number: "+48123456789",
  source_context: {
    foo: "bar",
    john: "doe"
  },
  onMessage() {
    alert("Received a message!");
  }
});

Sample message object:
Copied to clipboard!
{
  content: "Hello, world!",
  isAdmin: false
}

If isAdmin is set to true, it means that message came from backend side, otherwise it will be set to false and it means that message came from front-end widget.

onOpen()

Triggered when opening widget window.

Copied to clipboard!
UE.pageHit({
  apiKey: "YOUR_API_KEY",
  email: "johndoe@example.com",
  name: "John Doe",
  phone_number: "+48123456789",
  onClose() {
    alert("Closed a chat!");
  }
});

onClose()

Triggered when closing widget window.

Copied to clipboard!
UE.pageHit({
  apiKey: "YOUR_API_KEY",
  email: "johndoe@example.com",
  name: "John Doe",
  phone_number: "+48123456789",
  onClose() {
    alert("Closed a chat!");
  }
});

onPayloadReceived()

Can handle data sent through automation Send code module. Content of Send code module is passed as an argument to this method.

Copied to clipboard!
UE.pageHit({
  apiKey: "YOUR_API_KEY",
  onPayloadReceived: function(message) {
    console.log(message);
  }
});

Userengage method

Events

Copied to clipboard!
userengage("event.name",{
  event_attr1: "value1",
  event_attr2: "value2"
});

Send event with your custom name and desired event attributes. Remember, create event attributes with specific data types before sending them over to User.com. To learn more about events, click here.

Product events

Copied to clipboard!
userengage("product_event",{
  product_id: "value1",
  event_type: "add to cart",
  name: "product name",
  description: "this product description"
});

Using this method, you can trigger a product event on a specific action. To learn more about product events, click here.

Managing widget state
Copied to clipboard!
userengage("widget.{{state}}");

By referring to the widget object, you can easily manage your widget state. You can set up one of the following states:

State
Description
hide
Change widget state to hidden
open
Change widget state to expanded
show
Change widget state to standard
close
Closes opened chat window

Client update
Copied to clipboard!
userengage("client.update",{
  attribute: "value"
});

Using this method, you can update user attributes as well. However, it won't create a pageHit. Not every attribute can be changed with this method. Please, check the attributes' list here.

Vous êtes intéressé.e par les enjeux data et l’activation omnicanale ?

Nous sommes à votre disposition pour vous en dire plus lors d’une démo de la solution User.com.
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.