JavaScript Integration

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.

<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.

UE.resetAuth({
  apiKey: "YOUR_API_KEY"
});

‍

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

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.

UE.destroy({});

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.

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.

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:

{
  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.

UE.pageHit({
  apiKey: "YOUR_API_KEY",
  email: "johndoe@example.com",
  name: "John Doe",
  phone_number: "+48123456789",
  source_context: {
    foo: "bar",
    john: "doe"
  },
  onOpen() {
    alert("Opened a chat!");
  }
});

‍

onClose()

‍

Triggered when closing widget window.

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.

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

Userengage method

‍

Events

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

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

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: