Personalization

Using Javascript gives you access to ALL of your data to customize your mailings.

Konvey is the first and only email marketing platform to use Javascript (more specifically, ECMAScript 5.1) for personalization. Compared to proprietary merge codes in other email platforms, Konvey's server-side Javascript engine is far more powerful, elegant and standardized. It gives you direct access to your contact profile data, custom relational data, mailing metadata and a server-side API library.

For better or worse, the features and benefits of Konvey cannot be explained with a few bullet points and some dumbed-down marketing speak. We're going to go from zero to 100 MPH in the next few paragraphs to illustrate some of what can be done with Konvey.  It is important to know that understanding Javascript is not required to use Konvey. All of the Merge Codes can be accessed from the code editor or Email Builder components. Thus, knowing JavaScript is only necessary to accomplish the most complicated personalizations. Most I.T. departments and almost all web developers know how to write Javascript. It is one of the most basic and universal computer scripting languages. Creating highly dynamic mailings using the personalization engine is an advanced us of Konvey.

Javascript Expressions

The most basic type of personalization in Konvey is calling standard profile field data. Most email marketing platforms can personalize. We use server-side Javascript to do this rather than proprietary merge codes. As an example in Konvey, you can use this expression for a Contact's first name:

{% contact.firstname %}

In the example above,  contact is the name of a Javascript object (a contact profile), and  firstname is the name of a property on that object.  {%   and   %} are special characters that instruct Konvey's personalization engine to evaluate the enclosed text as server-side Javascript, instead of as literal HTML content.  

Since we're talking about Javascript—not a proprietary merge code syntax—it's also possible to do more complicated things, like changing the first letter of the name to upper case and appending “valued customer.”  This is a very simple example. Javascript expressions can achieve amazingly complex personalizations.

Dear {% contact.firstname && contact.firstname.trim().length > 0 ? contact.firstname[0].toUpperCase() + contact.firstname.substring(1) : "valued customer" %}:

The example above states: if the Contact has a first name, and the trimmed version of the first name (with leading and trailing spaces removed) is more than one character in length, then convert the first character of the first name to upper case, combine it with the remaining characters in the first name, and print it out in the HTML (or text) content; otherwise, print out "valued customer."

Contact Data

The properties of the contact object include all the common and custom Profile Fields in your data set, converted to all lower-case for sake of consistency. All of that data is available on the JSON tab in the Mailing Preview area, for all contacts marked as Testers.  Having this data available aids with testing and previewing content.

{
"contact": {
"contactid": 2147483655,
"firstname": "David",
"lastname": "Addison",
"purchaseamount": 288.2
/* more profile fields here */
},
"mailing": {
"mailingid": 2147493681,
"subject": "June 2017 Newsletter",
"fromaddress": "newsletter@mysite.konvey.net"
/* more mailing properties here */
}
}

The fields are displayed in JSON format, but you don't need to use JSON directly: it's just representing a Javascript object as text, to aid in crafting and testing personalization (e.g. we expose all contact data so that you have a reference while you're designing and testing your Mailings or Templates).

Related Table Data

If your Konvey account manager has configured one or more Related Tables for your site, you can optionally include that data in your personalized content. Unlike Contact data, which is always available (except in non-personalized online versions of your mailings), Related Table data will be available only if you explicitly reference it in your Javascript.

For example, if your site contains a Related Table named Purchases, your Javascript should contain a reference to  contact._purchases . The Related Table data is available as a child object of the contact object, with the name of the Related Table converted to lower-case and preceded by an underscore (to prevent conflicts with profile fields of the same name).

Konvey looks for Related Table references by literal text match, not by evaulating Javascript, and only three syntaxes are supported:  contact._purchasescontact["_purchases"] , and  contact['_purchases'] . Javascript code such as  var c = contact; return c._purchases;  and  var tableName = '_purchases'; return contact[tableName]; , while valid from a Javascript perspective, will prevent Konvey from recognizing the Related Table reference.

Some Related Table data is heirarchical in nature (i.e. nested multiple levels deep). The Purchases data, for example, might look like this:

{
"contact": {
"contactid": 2147483655,
"firstname": "David",
"lastname": "Addison",
"_purchases": [
{
"date": "2015-03-26T15:01:00-04:00",
"purchaseamount": 39.98,
"items": [
{
"name": "Widget",
"itemamount": 29.99
},
{
"name": "Contraption",
"itemamount": 9.99
}
]
}
]
/* more profile fields here */
}
}

A few other things to note about Related Table data:

  • As with profile fields, all property names in Related Table data are automatically converted to lower-case.
  • Although the property name of the related table is always preceded by an underscore (e.g. _purchases, in the previous example), property names of nested objects (e.g. items ) are not necessarily.
  • Most Related Table data is exposed as an array of objects, as in the example above. If, however, there is a one-to-one relationship between the Contact data and the Related Table data, then the Related Table may be exposed as a single object instead of an array of objects.
  • Some Related Tables contain data that is Site-specific, rather than Contact-specific. For example, a ski resort might have a Related Table named SnowConditions . That data is accessed the same way as Contact-specific data, however, as a property of the contact object.
  • Certain non-Contact-specific Related Tables (such as the SnowConditions one from the previous bullet point) are available even in the non-personalized Online Version of Mailings and on non-personalized landing pages. In that case, profile fields such as  contact.contactid and  contact.emailaddress would be undefined, but the  contact._snowconditions property would be populated with data if you referenced it in your Javascript.
  • Your Konvey account manager can configure Related Tables in many different ways, to meet different business needs. To determine how a specific Related Table will behave, reference it in Javascript somewhere in your mailing content, then preview the mailing to see the corresponding JSON-formatted data. And discuss it as necessary with your account manager, to make sure it meets your needs.

Filters

Saved Filters can be used to incorporate database-level logic and personalization into your Javascript. Each saved Filter you reference in Javascript automatically becomes a boolean (true/false) property on the contact object.

For example, if you've already saved a Filter named MaineResident, and you reference contact.$maineresident anywhere in your server-side Javascript, Konvey will automatically execute that Filter against the database and turn contact.$maineresident into a boolean property. Note that the Filter name is converted to lower-case and preceded by a dollar-sign character, to distinguish it from profile fields and Related Table data.

Of course, the previous example is unrealistic, because you could obtain the same boolean value entirely in Javascript (e.g. contact.state == 'ME') and not incur the slight performance penalty of an additional database query. But many saved Filters reference response data (Messages, Clicks, Opens, etc.) and subscription events that aren't available in Javascript.

Saved Filters—along with custom HTML attributes such as konvey-if—allow you to create a single, highly dynamic Mailing, instead of mulitple Mailings with different content and different filters.

Context

In addition to the built-in contact object, personalized content—and non-personalized content within the online version of a Mailing—will always contain a numeric Javascript variable named context. The purpose of this variable is to let you know the context in which the personalization is occurring. There are the possible values:

  • Email version of a Mailing
  • Online version of a Mailing
  • Landing Page

This allows you to create context-specific content using custom HTML attributes:

<div konvey-if="context == 1">This is the email version of the Mailing.</div>
<div konvey-if="context == 2">This is the online version of the Mailing.</div>

Custom Javascript functions

Konvey allows you to insert blocks of server-side Javascript directly into your content:


<script type="text/konvey-script">
    function getFormattedFirstName() {
        if (contact.firstname && contact.firstname.trim().length > 0) {
            return contact.firstname[0].toUpperCase() + contact.firstname.substring(1);
        } 
        else {
            return "valued customer";
        }
    }
</script>

The Javascript expression we used as a salutation in a previous example could then be rewritten:

Dear {% getFormattedFirstName() %}:

It's also possible to create a whole library of Javascript functions, saved as Snippets, and then include them in all your personalized content. For example, if you saved your Javascript functions in a Snippet named CommonJavascriptFunctions, then you could include that Snippet in your Mailing content using this special syntax:

{% $CommonJavascriptFunctions %}

Note that this is similar to the basic syntax for Javascript expressions in Konvey, except that the snippet name is prefaced with a dollar-sign character.

Javascript Expressions within HTML attributes

In addition to using Javascript expressions within your visible HTML and/or content, you can also use them within HTML attributes:

<p style="display: {% contact.state == 'ME' ? 'block' : 'none' %}">
   <!-- Some Maine-specific content here. --&rt;
</p>

In the example above, a Javascript expression specifies that the paragraph of text should have a CSS display style of "block" for Contacts who live in Maine ("ME") and "none" for everyone else: in other words, only Maine residents will see that paragraph of text. For this to work properly, the Javascript expression must evaulate to a boolean (true/false) value, not a string of text.

Javascript supports both single-quote and double-quote characters to encapsulate strings of text. Likewise, HTML attributes can be encapsulated by either single- or double-quotes. If you use double-quotes to encapsulate attributes—as in the example above—then use single-quotes within your Javascript expressions. You can also use the HTML entities " and ', because Konvey follows standard HTML rules.

In addition to using Javascript expressions within HTML attributes for styling your content, you can also use them for dynamically building the URLs of hyperlinks and images. For instance, you could append the contact.contactid value (which uniquely identifies Contacts within Konvey) or contact.remotecontactid (which is designed to store your own business-specific unique identifier) to the query string part of URLs pointing to your own website. If your website was designed to capture that value, you could use it to uniquely identify site visitors.

Custom HTML attributes

In the previous example, we hid a paragraph of content using conditional CSS. There are a few potential problems with that approach, though:

  • Content hidden via CSS is still available to any recipient who chooses views the HTML source.
  • Hidden content increases the size of the email message or Landing Page.
  • CSS based on Javascript expressions won't display correctly while you're using the Rich Text Editor to edit the mailing content, because your browser doesn't know how to evaulate those Konvey-specific expressions.

To deal with those issues (and many others), Konvey provides a set of custom HTML attributes that manipulate the HTML DOM (i.e. the collection of HTML elements on the page) using Javascript expressions. In the previous example, we could have used the konvey-if attribute to specify whether the paragraph of text—and its contents—should be present in the personalized content:

<p konvey-if="contact.state == 'ME'">
   <!-- Some Maine-specific content here. -->
</p>

In this case, the HTML source for non-Maine recipients won't contain that paragraph of text at all, so no CSS is required. Note that the Javascript expression isn't surrounded by the {% and %} encapsulators: Konvey's custom attributes don't require them, although you can use them if you'd like.

Most custom attributes, including konvey-if, can be applied to any type of HTML element, within reason (it wouldn't make sense to apply konvey-if to the <body&rt; tag, because that tag must appear in all HTML documents). Some attributes, however, should be applied only to specific HTML elements: the konvey-href attribute should be applied only to HTML elements such as that normally support an href attribute.

For detailed information on the Konvey custom attributes, consult the Personalization Reference.

Powerful Personalization for Sophisticated Marketers

What we've just outlined is a mere fraction of what can be accomplished with Konvey's personalization engine. We're glad to work with you to flesh out special uses cases and solutions. If you have questions about Konvey, you can always call us at 1-207-347-7360 Extension 212 We’re here to listen and help.