JavaScript Integration

Our basic JavaScript snippet is a block of code that you insert into your web app. It’s a low-impact way to send data to Engageful.io through your users' web browsers.

Important: Installing the JavaScript is required if you want in-app messages to be displayed on top of your website or application.

Add the JavaScript snippet

Below is an example snippet for Engageful. You should include this snippet on every page in your app, immediately before the closing </body> tag.

<script>
(function(w, d, s, o, f, js, fjs) {
  w['Engageful'] = o; w[o] = w[o] || function() { (w[o].q = w[o].q || []).push(arguments)};
  js = d.createElement(s), fjs = d.getElementsByTagName(s)[0]; js.id = o; js.src = f;
  js.async = 1; fjs.parentNode.insertBefore(js, fjs);
}(window, document, 'script', 'Engageful', 'https://www.engageful.io/js/v1/widget.js'));
</script>

Identify your users

You must identify people before you can add them to segments, campaigns, and send them targeted messages. You can do this by adding the init function to your HTML, beneath the JavaScript snippet.

Make sure to replace YOUR_SITE_ID with your own ID.

<script>
Engageful("init", {
    website: "YOUR_SITE_ID", // Important! Replace with your own ID.
    user: {
        // Required attributes — you must include the following
        id: "abc321", // Must be unique
        name: "John Doe",
        email: "[e-mail]",
        
        // Strongly recommended attributes
        created_at: 1339438758,   // Timestamp in your system that represents when
                                  // the user first signed up. You'll want to send it
                                  // as seconds since the epoch.
                                  
        // (Optional) - Include any additional attributes
        details: {
            plan_name: "premium",
            active: true,
            team_size: 10
        },
    },
});
</script>

When you send the init call, you must assign the website ID that they belong to. You can find the appropriate website ID from your Engageful dashboard.

You must send an identifier.

• id: the person’s unique identifier that maps a person to your backend systems.

• name: the person's full name.

• email: the person’s email address.

We strongly recommend that you send:

• created_at (a timestamp which represent when they first signed up)

You can also send in additional user attributes that are of value to you. In the above example we send plan_name, active and team_size attributes. You can use these attributes to segment your audience or to personalize messages when creating a campaign.

Send events

Events are actions people perform in your app, on your website, etc—things like button clicks, inviting a team member, or purchases. When you send us events, you can start campaigns and segment your users based on the things they do (or don’t do) in your app.

How do I send you event data?

First, ensure you’ve added our JavaScript snippet to every page where you’d like to send an event, then call event whenever your users take an important action you’d like us to track.

You can include any parameters associated with the triggered event, and filter campaigns based on those attributes.

Our tracking function works based on the current identified user, so there is no need to tell us which user to associate the event with, as long as you have done the basic integration above.

Here's an example event:

<script>
Engageful("event", {
    name: "plan_purchase", 
    // Optional event data
    details: {
        plan_name: "premium",
        referral: "facebook_ad"
    }
});
</script>

Track page views

Page views are events that record when a user visits a page on your site. With the page view data, you can segment your users based on pages they have or have not visited.

Once you've added our JavaScript snippet to your site, we will track page views on any page where that snippet is present.

Each page view event contains the title of the current page, and the URL including the host name, path name, and search parameters, helping you create campaigns depending on a user’s search terms, products that a person has filtered for, dates that a user is interested in, etc.