JavaScript Personalization

Last Updated: 26/6/2024     Tags: personalization, personalisation, integration, data, subscriber
  • Switch Version
  • V5
  • V4

Overview

Taguchi templates, activities and tracked URLs can use replacement tags to insert personalized data like subscriber names, email addresses or custom fields. Recipient data fields are available via the recipient object, and request data fields (covering the type of message being generated as well as additional content supplied via APIs) are available via the request object. These objects have global scope within template views, so logic based on recipient data can be included in JavaScript statement blocks.

Tag Generator

A simple personalization tag generator can be found here.


Basic Use

Insert subscriber or request data from default or custom profile fields using a personalization tag. An example of a basic personalization tag for a subscribers first name is as follows:

{%= recipient.firstname %}

Fallbacks

Fallbacks can also be implemented; the following outputs the recipient’s first name, or "Valued customer" if no first name is available:

{%= recipient.firstname || "Valued customer" %}

Subject Lines

To add personalization into your subject line, you should implement a tag using the personalization like the below:

{%! recipient.firstname %}

The difference between {%! %} and {%= %} is that {%= %} will replace special characters in your text, such as apostrophes and ampersands, with other special characters. To prevent this from happening, you need to wrap your personalization tag in {%! %} instead.

Conditional Formatting

Conditional formatting is also an added function, this example displays a salutation depending on the subscribers gender:

{% if(recipient.gender == 'Male') { %}Mr{% } else { %}Mrs{% } %}

Here is another common use case of conditional formatting.

{%= recipient.firstname ? recipient.firstname + ', y' : 'Y' %}our birthday gift is here.

If the recipient have their firstname (i.e. Taguchi), this will display "Taguchi, your birthday gift is here.".
For the ones who don't have their firstname, it will display "Your birthday gift is here." instead.

Lookups

Lookups can be implemented; the following converts abbreviated Australian state codes to their full names:

{%= {"VIC": "Victoria", "NSW": "New South Wales", "QLD": "Queensland",
    "NT": "Northern Territory", "WA": "Western Australia",
    "ACT": "Australian Capital Territory", "TAS": "Tasmania",
    "SA": "South Australia"}[recipient.state] %}

More complex expressions can be constructed, for example incorporating multiple recipient data fields or comparing data to an indexed array.


Recipient Data

The recipient object has the following fields:

Field Description
{%= recipient.id %} The Taguchi subscriber ID corresponding to the recipient (integer).
{%= recipient.hash %} The Taguchi subscriber authentication token for this recipient (integer).
{%= recipient.ref %} The recipient’s external ID.
{%= recipient.firstname %} The recipient’s first name.
{%= recipient.lastname %} The recipient’s last name.
{%= recipient.notifications %} Client-specific field used to store interests or messaging stream identifiers.
{%= recipient.phone %} Phone number.
{%= recipient.dob %} Date of birth (ISO-8601 YYYY-MM-DD format).
{%= recipient.address %} Postal address line 1.
{%= recipient.address2 %} Postal address line 2.
{%= recipient.address3 %} Postal address line 3.
{%= recipient.suburb %} Postal address city/suburb.
{%= recipient.state %} Postal address state.
{%= recipient.country %} Postal address country.
{%= recipient.postcode %} Postal address postal code/ZIP.
{%= recipient.gender %} Gender (no length/value restrictions).
{%= recipient.email %} Email address.
{%= recipient.organizationId %} The Taguchi organization ID to which this recipient belongs (integer).
{%= recipient.custom.<x> %} An object containing the recipient’s custom fields; a custom field named example would be accessed via recipient.custom.example.

All fields can contain string values of arbitrary length, unless otherwise specified. The encoding is UTF-8.

Request Data

The request object has the following fields:

Field Description
{%= request.id %} The Taguchi event ID corresponding to this request.
{%= request.test %} A flag indicating whether or not this request is being generated in test mode; 0 indicates the request is production, and 1 indicates the request is test. Production requests always use the last approved and deployed version of the activity content configured in the Taguchi UI, while test requests always use the latest version of the activity content.
{%= request.parent.X %} Any parent content supplied will be available within request.parent. For example, you can retrieve subscriber data from a parent request using request.parent.recipient.X (see above for recipient data).
{%= request.params.X %} If this request is for the generation of a web page or the “view online” version of an email, this object will contain the query-string parameters in the request URL (e.g. ?q=example will mean request.params.q evaluates to example).
{%= request.config.X %} An object containing hostname, the hostname of the Taguchi front-end server responsible for this request; mta, the hostname of the Taguchi MTA which will be used to send this request (if it’s an email), and tracking, which will be true if link tracking has been requested or false otherwise.
{%= request.content %} The Taguchi activity content used for this request (see the note on test above).
{%= request.additionalContent %} Any extra content that was submitted via an API call initiating this request, in JSON format. In order to access fields in this object (or its string value, if it is a string) you will need to call JSON.parse on it.
{%= request.activityId %} The Taguchi activity ID from which content was obtained.
{%= request.campaignId %} The Taguchi campaign ID associated with the activity.
{%= request.configurationId %} The configuration of multivariate test alternatives represented by the content structure.
{%= request.revisionId %} A unique, monotonically increasing identifier associated with the content version.