XML Submit Document
An XML Submit Document is sent to the Transact server by the user's system, which instructs the Transact server to send an email in response to a transaction on the user's system.
This article discusses topics that are related to the XML Submit document. Within this article, you will find:
- Example of an XML Submit Document Template
- Example of an XML Submit document
- Methods for Sending Content by using the XML Submit document
- XML Format
- Content and Formatting
Additonally, you will find information about:
- HTML
- CSS Stylesheets
- Hyperlink Tracking and Personalization - Dynamic Link Leader (DLL)
- Dynamic Link Leader (DLL) Encoding
- Composing a link
XML Submit Document Template
XML templates are XML files that contain the query string or stored procedure to be executed. Below is an example of this template.
<XTMAILING>
<RECIPIENT>
<EMAIL>[email protected]</EMAIL>
<BODY_TYPE>HTML</BODY_TYPE>
<PERSONALIZATION>
<TAG_NAME>World_Air_Confirmation_Body</TAG_NAME>
<VALUE>
<![CDATA[This is the <b>body</b> of the email.]]>
</VALUE>
</PERSONALIZATION>
</RECIPIENT>
</XTMAILING>
Example of an XML Submit Document
The code that is illustrated below is a brief example of what is typically generated by the user's backend system and is given for reference only. Transact uses standard XML syntax and the schema that is defined in Transact XML Submit Schema and the XML API section of the documentation. Data must be provided in this exact format.
Note:
A typical submission would not necessarily include all elements.
Methods for Sending Content by using the XML Submit Document
There are two methods for assembling a transactional email in Transact:
- Limit the Mailing template to serving as a simple placeholder for personalization tags while the rest of the content for the mailing is contained within the XML Submit document.
- Provide most of the HTML formatting in the mailing template, along with personalization tags that are interspersed in the formatting of the template. At mail generation time, only the values for the various personalization tags are merged into the template from the XML submission envelope.
See the Example Mailings article in this topic. It provides detailed examples of the two methods for assembling a transactional email in Transact.
XML Format
The user's system must specify the following information in the proper XML format:
- Campaign (Group) ID
- Contact email address
- Personalized content by Template tag name and value
The XML formatting must be exact. XML tags and tags can be in lower, upper, or mixed case, but tags must be exact. Booleans (true, false) must be in lowercase. Additionally, a template and corresponding campaign must be set up in your Acoustic Campaign organization.
If the user's system can't generate an XML document in the proper XML format, Professional Services can convert the file. Contact Client Support for more information.
The user's system can specify the following information in the proper XML format:
- Error response instructions, if other than the default
- Batch or individual processing instruction
- Save column instructions
- Transaction ID
- Updates to contact records
- Hyperlinks to track, with personalization
The Transact server returns a response document.
Content and Formatting
You can include content through several mechanisms, all of which use the Template field tags and the XML TAG_NAME / VALUE element. These include:
- Passing content through an XML TAG_NAME / VALUE element (corresponding to a template field tag).
- Using content that is hosted in the template by using a blank XML TAG_NAME / VALUE element.
- Passing content through a CDATA element nested in a TAG_NAME / VALUE element.
- Including a hyperlink to content on another server through one of the above methods.
Notes:
- XML Tags are alphanumeric fields. Punctuation and the following 'Reserve' characters are not allowed in the XML tags unless placed in a CDATA section (for example, ! * ' ( ) ; : @ & = + $ , / ? % # [ ]) . The underscore character "_" is an exception.
- You can only use an XML CDATA section within a TAG_NAME / VALUE element.
- You cannot nest a Transact XML tag within the CDATA section.
- You can include hyperlinks in a template or XML and use tracking with either.
- You can use Dynamic Content if you implement it on your backend system.
- Each tag (field) has a 4000-character limit, including white spaces.
Note:
Older databases might have a 255-character limit. Check with Client Support for more information or if the older database limit is an issue.
HTML
You can use text, XML, XSL, XHTML, HTML, and hyperlinks within a CDATA section or the template. See the example code in the XML Submit document below.
Notes:
- No processing of any code (logic or transformation) placed in text or CDATA content is done on the Transact server, including within Template tags.
- You can track hyperlinks in CDATA and XML text.
CSS Stylesheets
Transact supports CSS Style formatting within a CDATA element tag, which remains unparsed. The styles can be in the following formats:
- Inline styles
- Internal stylesheet
- Externally linked stylesheet.
See the example code in the XML Submit Document section above.
Acoustic Campaign can track hyperlinks that are submitted in the XML and XML CDATA (you can also include personalization). For more information on creating hyperlinks, see the Hyperlink Tracking and Personalization section in this document.
- XSL-style formatting, except as used in CDATA.
- Dynamic Content Rulesets from (however, Transact can reference dynamic content on the user's server).
- Share-to-Social
Contact Client Support for Professional Services on this and other web Service support.
Example of a Transact mailing
Use the code examples in the topic as a reference for your own Transact mailings.
Overview
This article includes the following examples of a Transact mailing submission:
- Mailing Template with content and personalization fields
2.XML Submission Document
a. Use with content in mailing template.
b.Use with an empty mailing template and content in HTML CDATA
Content in Template
The following example illustrates a complex application that uses a mailing template with content plus a number of fields that insert content that is passed from the XML document.
XML Submission Document: Use with content in a mailing template
Below is the sample XML Submission Document containing only the data for the personalization tags used for generating the mailing from the template.
Note:
Notice that there is a PERSONALIZATION element with a TAG_NAME/VALUE pair for each of the personalization tags in the mailing template. In the sample above, the values for the personalization tags are all text. In a real-world example, these personalization TAG_NAME\values can also contain HTML encapsulated in CDATA.
<XTMAILING>
<CAMPAIGN_ID>300402</CAMPAIGN_ID>
<TRANSACTION_ID>TRANS-1236</TRANSACTION_ID>
<SHOW_ALL_SEND_DETAILS>true</SHOW_ALL_SEND_DETAILS>
<SEND_AS_BATCH>false</SEND_AS_BATCH>
<NO_RETRY_ON_FAILURE>false</NO_RETRY_ON_FAILURE>
<RECIPIENT>
<EMAIL>[email protected]</EMAIL>
<BODY_TYPE>HTML</BODY_TYPE>
<PERSONALIZATION>
<TAG_NAME>PASSENGER</TAG_NAME>
<VALUE>Some info</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>RECORD_LOCATOR</TAG_NAME>
<VALUE>Body</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>TICKET_TYPE</TAG_NAME>
<VALUE>Body</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>TICKET_NUMBER</TAG_NAME>
<VALUE>0061296848484</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_TRAVEL_DATE</TAG_NAME>
<VALUE>Body</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_FLIGHT_NUMBER</TAG_NAME>
<VALUE>#545</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_DEPARTURE_TIME</TAG_NAME>
<VALUE> February 21, 10:00 AM EST (morning) </VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_TRIP_TITLE</TAG_NAME>
<VALUE>Atlanta Hartsfield-Jackson ATL (ATL)
to Salt Lake City International (SLC)</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_DEPARTURE_AIRCODE</TAG_NAME>
<VALUE>ATL</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_CLASS</TAG_NAME>
<VALUE>Economy</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_ARRIVAL_TIME</TAG_NAME>
<VALUE> February 21, 12:12 PM MST (afternoon) </VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_ARRIVAL_AIRCODE</TAG_NAME>
<VALUE>SLC</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_1_SEAT_ASSIGNMENT</TAG_NAME>
<VALUE>46B</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_TRAVEL_DATE</TAG_NAME>
<VALUE>Body</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_FLIGHT_NUMBER</TAG_NAME>
<VALUE>#3913</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_TRIP_TITLE</TAG_NAME>
<VALUE>Salt Lake City International (SLC)
to Boise Air Term. (Gowen Fld) (BOI)</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_DEPARTURE_TIME</TAG_NAME>
<VALUE> February 21, 3:10 PM MST (afternoon) </VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_DEPARTURE_AIRCODE</TAG_NAME>
<VALUE>SLC</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_CLASS</TAG_NAME>
<VALUE>Economy</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_ARRIVAL_TIME</TAG_NAME>
<VALUE> February 21, 4:16 PM MST (afternoon) </VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_ARRIVAL_AIRCODE</TAG_NAME>
<VALUE>BOI</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>FLT_2_SEAT_ASSIGNMENT</TAG_NAME>
<VALUE>7D</VALUE>
</PERSONALIZATION>
</RECIPIENT>
</XTMAILING>
XML Submission Document: For empty mailing template
Below is the sample XML submission document that uses an empty mailing template that contains only one personalization field: %%WorldAir_Confirmation_Body%%
We provide the content in the example formatted in HTML (within a CDATA section) and also use a stylesheet in the HTML.
<XTMAILING>
<CAMPAIGN_ID>300401</CAMPAIGN_ID>
<TRANSACTION_ID>TRANS-1234</TRANSACTION_ID>
<SHOW_ALL_SEND_DETAIL>true</SHOW_ALL_SEND_DETAIL>
<NO_RETRY_ON_FAILURE >false</NO_RETRY_ON_FAILURE>
<RECIPIENT>
<EMAIL>[email protected]</EMAIL>
<BODY_TYPE>HTML</BODY_TYPE>
<PERSONALIZATION>
<TAG_NAME>WORLD_AIR_CONFIRMATION_BODY</TAG_NAME>
<VALUE>
<!--CDATA section with HTML content and style sheet -->
<![CDATA[
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm...ansitional.dtd">
<html
xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv='Content-Type' content='text/html; charset=iso-8859-1' />
<title>Untitled Document</title>
<style type='text/css'>
<!--
.style1 {
font-family: Arial, Helvetica, sans-serif;
font-weight: bold;
font-size: 14px;
}
.style2 {
font-family: Arial, Helvetica, sans-serif;
font-weight: bold;
font-size: 24px;
}
.style4 {
font-family: Arial, Helvetica, sans-serif;
font-size: 14px;
}
.style5 {
font-family: Arial, Helvetica, sans-serif;
font-size: 10px;
}
-->
</style>
</head>
<body>
<img name="Cont_0" src="http://demo.worldair.com/world_air_banner.JPG">
<p>
<span class='style1'>Thank you for booking your
travel with World Air! Below is your confirmation of travel and your </span>
<br />
<span class='style1'>itinerary. Have a safe trip! </span>
<br />
<p>
<strong>Passenger(s):</strong> BILL JONES
<br />
<strong>World Air Lines record locator</strong>: PCCUOF
<br />
<strong>Ticket type requested:</strong> electronic (e-ticket)
<br />
<br />
<!-- fi -->
<strong>Orbitz record locator</strong>: 5I84Z8K5
<br />
<strong>Airline ticket number(s)</strong>: 0061296848482
<br />
<br />
<!-- lipt -->
<strong>Tuesday, February 21, 2006</strong>
<br />
World Air Lines # 545
<br />
<br />
Atlanta Hartsfield-Jackson ATL (ATL) to Salt Lake City International (SLC)
<br />
<strong>Departure (ATL):</strong> February 21, 10:00 AM EST (morning)
<br />
<strong>Arrival (SLC):</strong> February 21, 12:12 PM MST (afternoon)
<br />
<br />
<strong>Class:</strong> Economy
<br />
<!-- seatmap -->
<strong>Seat assignment:</strong> 46B
<a
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=1"
href="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=1">
<br
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=1" />
view/change seats
</a>
<br />
<!-- end carrierSupported = true -->
<!-- end hasStarted = false -->
<!-- end hasSeatAssignments = true -->
<br />
<!-- lipt -->
<strong>Tuesday, February 21, 2006</strong>
<br />
World Air Lines # 3913
<br />
Operated by: SKYWEST AIRLINES - Please check in with the operating carrier
<br />
<br />
Salt Lake City International (SLC) to Boise Air Term. (Gowen Fld) (BOI)
<br />
<strong>Departure (SLC):</strong> February 21, 3:10 PM MST (afternoon)
<br />
<strong>Arrival (BOI):</strong> February 21, 4:16 PM MST (afternoon)
<br />
<br />
<strong>Class:</strong> Economy
<br />
<!-- seatmap -->
<strong>Seat assignment:</strong> 7D
<a
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=2"
href="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=2">
<br
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=2" />
view/change seats
</a>
<br />
<!-- end carrierSupported = true -->
<!-- end hasStarted = false -->
<!-- end hasSeatAssignments = true -->
<br />--------------------------------
<br />
<br />
<!-- lipt -->
<strong>Thursday, February 23, 2006</strong>
<br />
World Air Lines # 488
<br />
<br />
Boise Air Term. (Gowen Fld) (BOI) to Salt Lake City International (SLC)
<br />
<strong>Departure (BOI):</strong> February 23, 8:00 AM MST (morning)
<br />
<strong>Arrival (SLC):</strong> February 23, 9:05 AM MST (morning)
<br />
<strong>
<br />
Class:
</strong> Economy
<br />
<!-- seatmap -->
<!-- has no seat assignment -->
<strong>Seat assignment:</strong>
<a
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=3"
href="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=3">
<strong
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=3">
choose seats</strong>
</a>
<br />
<br />
<!-- lipt -->
<strong>Thursday, February 23, 2006</strong>
<br />
World Air Lines # 646
<br />
<br />
Salt Lake City International (SLC) to Atlanta Hartsfield-Jackson ATL (ATL)
<br />
<strong>Departure (SLC):</strong> February 23, 10:10 AM MST (morning)
<br />
<strong>Arrival (ATL):</strong> February 23, 3:50 PM EST (afternoon)
<br />
<br />
<strong>Class:</strong> Economy
<br />
<!-- seatmap -->
<strong>Seat assignment:</strong> 42E
<a
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=4"
href="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=4">
<br
title="http://www.orbitz.com/App/MyStuffVie...seatMapIndex=4" />
view/change seats
</a>
<br />
<!-- end carrierSupported = true -->
<!-- end hasStarted = false -->
<!-- end hasSeatAssignments = true -->
</p>
<p>If you would like to change your mailing settings,
click
<u>here</u> to edit your web profile.
</p>
<p>
<a xt="SPCLICK" name="www_spopdemo_com"
href="http://www.spopdemo.com">click here for spop</a>
</p>
</body></html>
]]>
<!--End CDATA section -->
</VALUE>
</PERSONALIZATION>
</RECIPIENT>
</XTMAILING>
Hyperlink Tracking and Personalization – Dynamic Link Leader (DLL)
Transact can track hyperlinks that are submitted in the XML CDATA that uses Dynamic Link Leader (DLL) URL encoding.
When you are submitting encoded links in the XML document, URLs that are clicked are tracked. The resulting data is available in the reporting section.
Notes:
- You can use personalization within the URL, but you must include the personalization field and value in the XML submission. This allows to make the correct substitutions from the database when a contact clicks the encoded URL.
- This section is only for links that are submitted in the XML file. Automatically tracks all links that are created within the Mailing Template (with no additional development work required).
The Host Server URL is links.<org_specific_domain> and is applicable to Pods 1-7.
Configure an XML Submission with Tracked Links
To configure an XML Submission with tracked links:
- Convert the URLs in the submission to DLL-encoded links.
- If URLs contain personalization, add elements for each field to the SAVE_COLUMNS section and to the PERSONALIZATION section with the correct value for the contact.
- Make sure that the contact database contains the fields corresponding to the personalization elements defined in the XML submission (for example, custom fields).
- Perform a test send, click links in the received mailing, and make sure that the redirected URL contains the correct link and personalization substitutions.
- Check reporting after you allow enough time for the tracking to occur and display.
Notes:
- If you have a custom domain available, use it. For example, links.customdomain.com
- For personalization values to appear in the mailing, you must include the value in the Mailing Body of the Mailing Template.
- To save the personalization values in the database, you must create the fields in your database and use the SAVE_COLUMN element for that XML tag.
- Dynamically generated links that are on the sending system are included in the XML that uses the CDATA tag in the Personalization section within a CDATA section.
Dynamic Link Leader (DLL) Encoding
You can include links (dynamically generated on the sending system) in the XML by using a CDATA section in the Personalization element. Can then track these hyperlinks for clicks. In addition, you can include personalized information, such as account numbers, within the hyperlink and save it as query string values.
You need to identify trackable links by preceding them with a Link Name, as shown in the example below:
<PERSONALIZATION>
<TAG_NAME>XX</TAG_NAME>
<VALUE>
<![CDATA[ Insert link and other information
in place of this text ]]>
</VALUE>
Format:
<![CDATA[Here is a link:
<[link name and type]a href="">Click here</a> ]]>
Composing a link
The following illustrates how to compose various links for the transaction email. In the sample transaction email below, the following hyperlinks are illustrated:
- A hyperlink to the sponsor's website with tracking but no personalization. (Link A)
- A hyperlink to a lodging website with tracking. (Link B)
- A hyperlink to a special offer website with an offer number and tracking. (Link C)
See the examples below for the preferred composition of links A, B, and C in the XML Submit section.
###Link A: Hyperlink to the sponsor's Web site included in the mailing body
Example 1 - Contact View (Email Message)
Example 2 - Mailing Template
XML Personalization
You do not need a Personalization element for this example. It will automatically track all hyperlinks included in the mailing body. You can also place text and hyperlinks in the XML (see Link B example below).
Link B: Hyperlink to a lodging Web site (with tracking)
Create a hyperlink to substitute using a field (HotelBrand_Link) in the template text:
Example 1 - Contact View (Email Message)
In the example email text, you would need to use another XML tag and Template field (both not shown) to change the “SleepBetter” brand name to correspond with the hyperlink.
Example 2 - Mailing template
Example 3 - XML
<PERSONALIZATION>
<TAG_NAME>HotelBrand_Link</TAG_NAME>
<VALUE>
<![CDATA[
<a href="http://links.<org_specific_domain>/ctt?m=%%MAILING_ID%%&r=%%RECIPIENT_ID%%&b=0&j=%%JOB_ID_CODE%%&k=Lodging_Link&kx=1&kt=12&kd=http://www.sleepbetter.com">Click here</a>
</VALUE>
</PERSONALIZATION>
Example 4 – URL with Query String
The first part of the string is a constant and must be included for tracking:
<a href="http://links.<org_specific_domain>t/ctt?m=%%MAILING_ID%%&rj=%%REPORT_ID_CODE%%&r=%%RECIPIENT_ID%%&b=0&j=%%JOB_ID_CODE%%">
Notes:
- Do not insert information in place of the %%X%% placeholders.
- If you have a custom domain available, use it. For example, links.customdomain.com
- You must create a field for the link in (such as HotelBrand_Link) in both the database and the Mailing Template. You can also place the text in the Template (if the link will always be there), or dynamically place it in the XML CDATA section with the hyperlink.
- The value for the tag (HotelBrand_Link) can accommodate all text, including HTML and styles.
Example:
<VALUE><![CDATA[<p><b><style “color:#FF0000”>Thank you for booking with</style>
<a href="http://www.abc-travel.com">ABC-Travel.com</a>]]>
Notes:
- This example does not show tracking information.
- All information that is placed in the XML must appear within the Personalization element for each contact (if used). For example, if there are ten contacts, you can enter the information ten times.
- It is not necessary to use the SAVE_COLUMNS element for this hyperlink and text unless you want to save the values to the database for future reference.
The remainder of the Query string includes the actual hyperlink and personalization:
&k=Lodging_Link&kx=1&kt=12&kd=http://www.sleepbetter.com
Parameter: Name and Value | Description |
---|---|
&k=Lodging_Link | Name of the link. This name is the tracking tag and identifies the link in clickthrough reports. |
&kt=12 | Specify the type of hyperlink. 1 Regular 12 Personalized 5 Clickstream |
&kd=http://www.sleepbetter.com | The destination hyperlink ta": { "h-0": "Parameter: Name and Value", "h-1":. |
&kx=1 | Link cross-reference. Specify whether to use the KD you entered above (or to default to the database). 0 Ignore KD link above and default to database (not preferred). 1 Ignore database and use destination specified in KD above (typical). |
If you plan to have all text that is dynamically placed in the XML CDATA section, the CDATA section with the tracking hyperlink should appear as follows:
<PERSONALIZATION>
<TAG_NAME>HotelBrand_Link</TAG_NAME>
<VALUE>
<![CDATA[Have you made lodging arrangements? %%Brand%%
<a href="http://silverpop.com/ctt?m=%%MAILING...leepbetter.com">Web site</a>.
]]>
</VALUE>
</PERSONALIZATION>
Link C: Hyperlink to a Web site using a personalized offer number and tracking
Personalizing links with unique data, such as unique special offer codes and account numbers, requires the use of a query string and possibly additional personalization tags with corresponding values and tag substitutions. By embedding the URL query string for the destination website with parameters, you can insert special offer codes automatically in forms at the site, and tracking can be done on the website to determine the effectiveness of advertising and clickthroughs. Parameters appear in the query string for easy correlation with information.
You can insert data-embedded query strings as a complete string, or you can use personalization tags to complete the string. See the example below to view how to use personalization tags to construct the message and complete the query string.
Note:
The following message and code is an example of a standardized entertainment promotional message and hyperlink that you can place in each Transaction Response email. It is customizable so you can insert different sponsor names into the message with different URLs and different promotional codes that appear in the message and the query string. can track clickthroughs showing how many clicks each sponsor received.
This example shows the brand name, tracked hyperlink, and promotional code to substitute that uses fields and XML tags (Brand, code, Promo1 with query string code) in the Template text.
Example 1 - Contact View (Email Message)
Example 2 - Mailing Template
Example 3 - XML
Example 4 - Parameters and Query String
The following table provides the parameters and query string used in the preceding code: &k=PromoSB&kx=1&kt=5&kd=http://www.starchasers.com%3FCode%3D%25%25Code%25%25
Parameter: Name and Value | Description |
---|---|
&k=PromoSB | Link Name parameter and name. This is the tracking tag and you must give a different name for each hyperlink. You can view this information in the Clickthroughs area of the Reporting section. Note: If you do not change this name, forwards the clickthrough to the hyperlink associated with the name, not the newly embedded hyperlink. |
&kt=5 | 5 - Clickstream (personalized and tracked) |
&kd=http://www.starchasers.com%3FCode%3D%25%25Code%25%25 | Hyperlink (illustrated in the query string with a Personalization tag). Do not include quotation marks (‘) around the hyperlink. Important: Use the UTF-8 character hexadecimal equivalents for non-alphanumeric characters. |
kx=1 | Link cross-reference. Specify whether to use the KD you entered above (or to default to the database). 0 – Ignore KD link above and default to database (not preferred). 1 – Ignore database and use destination that is specified in KD above (typical). |
Notes:
- Automatically places the Brand and Code values in the message, and in the hyperlink query string. (Brand and Code are tags and values that are placed by you in the XML Personalization section.)
- You must add the personalization fields to the database (Brand, Code, and Promo1 in the example above). Do not add an XML tag for the "&k"parameter.
- You must use the SAVE_COLUMN element to ensure the personalized hyperlinks work for your contacts.
- The parameters (
MailingID
,UserID``JobID
, andReportId
) appears in the query string at the destination website. Other parameters, such as CAMPAIGNID and email address, do not appear unless you include them as XML personalization (both tag and value) and query string parameters.
What to Expect - String Appearance
In the "Link C" example above, you can expect to see different strings at different phases in the communication process. The submitted XML, the email hyperlink, and the browser redirect all have different characteristics. In the example, you would see the following:
<PERSONALIZATION>
<TAG_NAME>Brand</TAG_NAME>
<VALUE>StarChasers</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>Code</TAG_NAME>
<VALUE>441605</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>Promo1</TAG_NAME>
<VALUE>
<![CDATA[
<a href="http://links.<org_specific_domain>/ctt?m=%%MAILIN...PIENT_ID%%&b=0
&j=%%JOB_ID_CODE%%&k=PromoSJ&kx=1&kt=5&kd=http://www.starchasers.com
%3FCode%3D%25%25Code%25%25">Web site</a> ]]>
</VALUE>
</PERSONALIZATION>
Example 2 - Email Message Hyperlink HTML (source view of the email after sending)
Example 3 - Browser Redirect URL with Query String
http://www.starchasers.com/?Code=441605
- Separate one parameter from the next with an ampersand (&). For example, ?m=4&x=5.
- Separate the name-value pairs with an equal sign (=). For example, ?m=12345.
- XML is case-sensitive and UTF-8 uses different symbols for uppercase and lowercase characters.
Example
http://www.starchasers.com/?code=123&...ccount=8016428
DLL Query String Parameters
Here's a list of DLL query string parameters and their values:
Name | Value |
---|---|
Server URL | URL of the clickthrough tracking (CTT) servlet on the server. See table on page 55 for a list of Server URLs for each pod. |
?m | Mailing ID for the submission (system substitution – user supplies placeholder only). |
&r | Recipient ID for the submission (system substitution – user supplies placeholder only). |
&b | Mailing body type: 0 – HTML 1 – <Deprecated. Formerly the AOL body type> 2 – TEXT 3 – Click to View |
&j | Job ID for the submission that is being sent (system substitution – user supplies placeholder only) |
&k | Name for the link that is specified by the link creator. Often used to differentiate between multiple links in a mailing with a descriptive name, making it easy for users to identify. For example, “&k=left_banner_link” “&k=bottom_left_logo_link” “&k=sponsor_Sleepwell” |
&kt | Link type: 1 – Regular hyperlink. ( can track.) 12 – Personalized hyperlink. Link that has a personalization field unique to each contact. The link name must be the same for every contact, but substitutes the value based on the contact. ( can track.) 5 – Clickstream hyperlink. A link that opens a browser window to a website and then provide tracking for various actions that are performed at that website. ( can track.) |
&kd | Contains the encoded URL to use as the foundation of the URL to process, send to the contact’s browser, and redirect. Important: You must encode this portion of the query string or the personalization does not work. |
&kx=1 | Link cross-reference. Specify whether to use the KD you entered above (or to default to the database). 0 – Ignore KD link above and default to database (not preferred). 1 – Ignore database and use destination specified in KD above (typical). |
Example 1 - Sample XML Submission with DLL-Encoded Links and Personalization
<XTMAILING>
<CAMPAIGN_ID>numeric CAMPAIGN id</CAMPAIGN_ID>
<TRANSACTION_ID>TRANS-1234</TRANSACTION_ID>
<SHOW_ALL_SEND_DETAIL>false</SHOW_ALL_SEND_DETAIL>
<SEND_AS_BATCH>false</SEND_AS_BATCH>
<NO_RETRY_ON_FAILURE >false</NO_RETRY_ON_FAILURE>
<SAVE_COLUMNS>
<COLUMN_NAME>ACCOUNT_ID</COLUMN_NAME>
</SAVE_COLUMNS>
<RECIPIENT>
<EMAIL>[email protected]</EMAIL>
<BODY_TYPE>HTML</BODY_TYPE>
<PERSONALIZATION>
<TAG_NAME>ACCOUNT_ID</TAG_NAME>
<VALUE>807</VALUE>
</PERSONALIZATION>
<PERSONALIZATION>
<TAG_NAME>TRANSACT_MAIL_BODY</TAG_NAME>
<VALUE>
<![CDATA[
<p>Click this link: <a href="
http://links.<org_specific_domain>/ctt?m=%%MAILIN...count_ID%25%25">link</a><p>
]]>
</VALUE>
</PERSONALIZATION>
</RECIPIENT>
</XTMAILING>
In the sample XML submission above, the sections relevant to DLL Link Tracking are highlighted in bold and explained as follows:
- The <SAVE_COLUMNS> element contains the personalization element. By placing the "ACCOUNT_ID" personalization in the <SAVE_COLUMNS> section, stores the value for this field in the database that is associated with the Transact Automated Message Group in along with system field data for the record.
- The element contains the "ACCOUNT_ID" personalization element with its corresponding value for the contact of this Transact email. When the mail is sent to the contact, "ACCOUNT_ID" database column is updated with the value ("807" for this record) along with the system columns.
- The Dynamic Link Leader-encoded URL is the URL placed in the mailing. When the contact clicks the link, it resolves to the tracking servlet. The servlet processes the URL parameters and updates the tracking data. Personalization substitutions are made and the contact's browser is redirected to the correct URL destination specified in the "&kd" parameter.
Note:
You can also provide static personalization information through a Template and use Tracking.
Encoding the KD parameter
You must encode the KD portion of the query string with non-alphanumeric characters.
Important:
If you do not encode with non-alphanumeric characters, identical personalization information is sent in every email. Characters (such as question marks, equal signs, and percent symbols) are encoded using the UTF-8 character set equivalents in hexadecimal, preceded by the percent symbol (%). See the examples and encoding table below for more information.
Unencoded string
kd=http://www.spdemo.com?AccountID=%%Account_ID%%">link</a>
Encoded string
kd=http://www.spdemo.com%3FAccountID%3D%25%25Account_ID%25%25">link</a>
UTF-8 (Unicode) hexadecimal encoding substitutions for non-alphanumeric characters:
Character | Hexadecimal equivalent | Character | Hexadecimal equivalent |
---|---|---|---|
! | 21 | , | 2c |
‘ | 22 | – | 2d |
# | 23 | . | 2e |
$ | 24 | / | 2f |
% | 25 | : | 3a |
& | 26 | ; | 3b |
` | 27 | < | 3c |
( | 28 | = | 3d |
) | 29 | > | 3e |
* | 2a | ? | 3f |
+ | 2b | @ | 40 |
For more information, see http://www.utf8-chartable.de/ or http://www.unicode.org
Clicked Tracking Hyperlink with Personalization Limitations
When you are using dynamic hyperlinks in the XML document, note the following:
- You must specifically state that you want to save the XML columns that contain the data in the database. The server performs the substitutions for personalized links by using data in the saved columns.
- When you are placing hyperlinks in CDATA, insert the corresponding personalization values in the XML Personalization section.
- You must completely compose XML-embedded hyperlinks on your system.
- You must provide a default value in case the hyperlink personalization is incomplete either because it was not submitted in the XML, or information is not yet synchronized due to a slight delay with the server.
- Limit personalization strings to 4000 characters. Data and markup over 4000 characters are not stored.
Note:
Older databases can have a 255-character limit. Check with support for more information if this is an issue.
- The number of links that are included in the XML submission is not limited.
- Acoustic Campaign does not track improperly formed hyperlinks in the XML. For example, do not use personalization that is unique to your system without following the personalization requirements in this section. Avoid using such personalization as it might cause server issues and delays.
XML Submit Document Schema
We provide the following schemas for Transact for illustrative purposes only. We do not recommend copying schemas and using them for XML validation in a production environment without thorough testing.
Submit Document Schema Rev 1.2
<xsd:schema
xmlns:xt=
"http://www.silverpop.com/XTMailing"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="unqualified" attributeFormDefault="unqualified">
<xsd:element name="XTMAILING">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="CAMPAIGN_ID" type="xsd:long"/>
<xsd:element name="TRANSACTION_ID"
type="xsd:string" minOccurs="0"/>
<xsd:element name="SHOW_ALL_SEND_DETAIL"
type="xsd:boolean" default="false" minOccurs="0"/>
<xsd:element name="SEND_AS_BATCH"
type="xsd:boolean" default="false" minOccurs="0"/>
<xsd:element name="NO_RETRY_ON_FAILURE"
type="xsd:boolean" default="false" minOccurs="0"/>
<xsd:element name="SAVE_COLUMNS" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="COLUMN_NAME"
type="xsd:string" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="RECIPIENT" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="EMAIL" type="xsd:string"/>
<xsd:element name="BODY_TYPE" type="xsd:string"/>
<xsd:element name="PERSONALIZATION"
minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="TAG_NAME" type="xsd:string"/>
<xsd:element name="VALUE" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Updated about 1 year ago