August 20, IBM Marketing Center Template and Web Developer Guide

Transcription

1 August 20, 2014 IBM Marketing Center Template and Web Developer Guide

2 Note Before using this information and the product it supports, read the information in Notices on page 45. IBM Digital Marketing and Analytics is the new generation of IBM Coremetrics products. See this table for details on new product naming. Previous Product Name IBM Coremetrics AdTarget IBM Coremetrics Benchmark IBM Coremetrics Enterprise Analytics IBM Coremetrics Explore IBM Coremetrics Import IBM Coremetrics Export IBM Coremetrics Intelligent Offer IBM Coremetrics Lifecycle IBM Coremetrics LIV IBM Coremetrics Monitor IBM Coremetrics Search Marketing IBM Coremetrics Social Analytics IBM Coremetrics Tag Manager IBM Coremetrics Web Analytics New Product Name IBM AdTarget IBM Digital Analytics Benchmark IBM Digital Analytics Multisite IBM Digital Analytics Explore IBM Digital Analytics Import IBM Digital Analytics Export IBM Digital Recommendations IBM Digital Analytics Lifecycle IBM LIV IBM Digital Analytics Monitor IBM Search Marketing IBM Digital Analytics for Social Media IBM Digital Data Exchange IBM Digital Analytics The documentation distributed with the IBM Digital Analytics products is confidential and proprietary to IBM and as such is subject to the provisions of any confidentiality agreement executed between the parties. Regardless of the specific provisions of any such confidentiality agreement, the parties hereby agree to treat the referenced documentation as the confidential information of IBM and further agree not to distribute such documentation to any third party or to copy such documentation except as expressly permitted in any license agreement between the parties pertaining to such products. Licensed Materials - Property of IBM Copyright IBM Corporation 2009, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents Chapter 1. Introduction Template and web page coding requirements, conventions, and tips Ensure that template code is XHTML-compliant. 1 Plan the zones Valid zone IDs Formatting the hyperlinks generated by the Hyperlink widget How to write HTML snippets for zones Chapter 2. Creating templates.. 5 Styles for s must be inline (embedded in the document) Templates and naming conventions Configuring zones for templates Use text in each zone Coding templates for text-only messages... 7 Coding the static sections Including personalizations in templates Including personalized images in a transactional template Design for deliverability Uploading and testing the template Chapter 3. Preparing your site for Marketing Center If a web page is tagged with multiple client IDs.. 13 Configure elements for website personalizations.. 13 How JavaScript is loaded into your web pages.. 13 Chapter 4. Enabling users to opt-out of communications Using the standard CDN-hosted opt-out page Hosting your own opt-out page The complete JSONP response Chapter 5. The Marketing Center API 23 Testing your client ID and security token Access and update engagement data via the Marketing Center API Retrieving a list of fields Retrieving data for a single customer Updating customer data Building and deploying campaigns remotely About building campaigns and deploying and undeploying builds Chapter 6. Creating the local transactional client Including personalized information in transactional requests Sending attachments in transactional s Including personalized images in transactional requests Transactional process flow The Transactional Mailing Service API mailingcode audienceid fields cellcodes additionaloptions attachments trackingfields locale username password NameValuePair Response AdvisoryMessage Error messages for transactional Appendix. Sample second-generation client Notices Trademarks Privacy Policy Considerations Copyright IBM Corp. 2009, 2014 iii

4 iv IBM Marketing Center Template and Web Developer Guide

5 Chapter 1. Introduction IBM Marketing Center is a console from which marketers create, manage, and deploy campaigns and mailings that deliver personalized communications to audience members. Some communication types and features require you to complete associated HTML template, web page, or web application work outside Marketing Center. If your organization uses Marketing Center to deliver , you must create templates. Templates define the static content and the sections that can be customized. If your organization uses Marketing Center to deliver personalized web pages, you must designate the areas that can be customized. Your site must also be tagged for Marketing Center. If your organization is providing a web page where your customers can choose not to receive , you must create that page or link to a page that IBM hosts. If your organization uses Marketing Center to send transactional s, you must create the local transactional client. Template and web page coding requirements, conventions, and tips Because you cannot control where your message is viewed, ensure that the HTML in your templates and web pages is well-formed and compliant with XHTML. The people that your marketers target have many different browser technologies available to them. Some browsers, especially those browsers that are designed for mobile devices, cannot interpret poorly formed HTML. Keep in mind the following tips: v Specify the character encoding for text. In most cases, use the Unicode encoding, UTF-8, so the text from your messages displays properly in clients and in browsers. v Be sure to include alt="image description" information for all images. Image descriptions are an important accessibility aid, and can also provide useful information if the image does not render. v Unless you are quoting something in a language other than English, do not use the» character entity. Instead, use two > character entities. v The character entity for the horizontal ellipsis (...) is supported in HTML and XHTML, but it is not valid in XML. Therefore, it is best to use three periods rather than the character entity when you must use a horizontal ellipsis. Ensure that template code is XHTML-compliant While it is not a requirement, you are encouraged to use XHTML-compliant code in your HTML templates. There are four main differences between XHTML elements and HTML tags. XHTML elements: Copyright IBM Corp. 2009,

6 v v v v Must be properly nested Must always be closed, even for self-contained tags like <br/> Must be in lowercase Must have one root element Many websites describe the differences between HTML and XHTML in more detail. If you have questions, search for tutorials and information. For example, see the following websites: v w3schools.com v XHTML.org Use an HTML validator to test your templates before you upload them to IBM Marketing Center. That way you can avoid potential problems later when marketers use the templates to create a communication. You can download a tool like JTIDY. Or you can use an online validator like the one available from the W3C. Plan the zones When you design the HTML and add the zones, you configure them to support the type of content you expect to be dropped into each zone. To control the size and appearance of a zone, put the styles in the area that surrounds the zone. When you are determining the styles and size for a zone, be sure to consider each type of content that might be dropped into it. Marketers can add content to zones by selecting content from the digital asset library or by using content widgets. The following table lists the content widgets. Table 1. Content Widgets Widget Description Text Block displays an embedded text editor for manually entering text and personalization fields. The text can include HTML formatting tags. Hyperlink displays a form for adding a hyperlink to a web page. The page can be any existing page accessible through the internet. The hyperlink can either be text or an image. Image displays a form for entering the URL to an externally hosted image. Images from the library can be dragged from the side navigation pane and dropped directly into the zone. Field displays a list of the fields that can be used to customize the message to the recipient. The fields that are available depend on your data. View as Web Page allows you to insert a link to a web page that displays the content of your communication. Content Connector displays a form for entering the URL or file path to externally located HTML or text content. This widget is available in communications only. 2 IBM Marketing Center Template and Web Developer Guide

7 Valid zone IDs Each zone in your template or on your web page must have a valid ID. Campaigns that contain a communication with an invalid zone ID do not work. A campaign cannot be deployed successfully if it contains an communication that uses a template with an invalid zone ID. A site communication for a page with an invalid zone ID never displays its content to your site visitors. All zone IDs must meet the following conditions: v The first character must be a letter. v The zone ID can include only letters, numbers, and the underscore character. v The zone ID cannot include spaces. v The zone ID must be unique in the template or web page. You cannot use capitalization to distinguish one zone ID from another. All zone IDs are converted to uppercase when they are processed, so GivenName and givenname are considered to be the same zone ID. Formatting the hyperlinks generated by the Hyperlink widget Generally, the zones use the formatting that is defined by the styles that are embedded in the HTML template without any additional coding. When you know that users will drop a Hyperlink widget into an area, however, you must apply an extra <span> element to force the generated link to use a specific style. For example, say that you are creating a zone in a template for a link. You can add a style element called "linkwrapper" to define the formatting for the hyperlink: <style type= text/css">.linkwrapper a {color #999} </style> Then, you surround the zone that contains the hyperlink with an extra <span>, setting the class to "linkwrapper": <span class="linkwrapper"> <span id="link0" class="droppable">link</span> </span> How to write HTML snippets for zones HTML snippets are small sections of HTML code that marketers can use in a zone. Snippets are stored in IBM Marketing Center. Limit the HTML code in your snippets to formatting tags: <b></b>, <br/>, and <h3></h3>, for example. Never include <body> or <head> tags in a snippet of HTML that is meant to be used in a zone. For example, following is an HTML snippet: <b>aenean ornare luctus enim, a aliquet urna congue quis!</b> <br/> Cras ultrices convallis urna, quis iaculis odio auctor ut. <ul> <li>quisque in lacus lectus.</li> <li> Nullam dictum libero ac metus tincidunt hendrerit.</li> <li>vestibulum aliquam porttitor lorem et laoreet.</li> </ul> Chapter 1. Introduction 3

8 4 IBM Marketing Center Template and Web Developer Guide

9 Chapter 2. Creating templates An template is an HTML file that specifies certain areas as zones. Zones define where content on the page can be changed when the template is used. To create the HTML templates, use your own third-party HTML editor. Design the templates and designate which areas are zones. Then, upload the templates to Marketing Center. When marketers use the templates to create s, they can replace and edit the content in the zones. Styles for s must be inline (embedded in the document) Because not all clients support css, do not provide styles and formatting in external css files. For best results, embed all style definitions in the template. Templates and naming conventions When users create an communication, they must select a template from the library. Use a naming convention that indicates the purpose of the template clearly enough that users can determine which template to choose when they create communications. Additionally, you can use folder names in the library to organize the template files. Configuring zones for templates Zones are the areas that marketers can customize when they create communications in IBM Marketing Center. You can specify that an area in the template is a zone by using the ID attribute or the class attribute. You specify that a section or area is customizable in one of the following two ways: v v Include a value for the ID attribute of the element that defines the section. The value that you specify for the element ID is displayed as the label for the zone when the template is used for a communication. To specify that only some of the elements are zones (and some are static), add the class attribute named droppable to the elements you want to be zones. In other words, if none of the elements are marked with the droppable class attribute, then any element with an ID attribute is a zone. But if any elements have the droppable class attribute, those elements are interpreted as zones while elements without the droppable class attribute are not. To create a template that has areas that are not modifiable, you must use the droppable class attribute to specify which elements are zones and which are not. Example 1: Using the ID attribute The following code sample creates five zones by using the ID attribute. <table> <tbody> <tr> Copyright IBM Corp. 2009,

10 Use text in each zone <td><img id="banner" alt="whatchamacallit"/></td> </tr> <tr> <td> <ul class="nav"> <li>page 1 </li> <li>page 2 </li> <li>page 3 </li> </ul> <img id="ad1" alt="ad1"/> </td> <td valign="top"> <div id="body"> <p>lorem ipsum dolor sit amet, consectetur adipiscing elit. </p> </div> </td> <td> <img id="ad2" alt="ad2"/> <img id="ad3" alt="ad3"/> </td> </tr> </tbody> </table> Example 2: Using the droppable class attribute The following code sample uses the droppable class attribute to create five zones. Elements that have an ID attribute but do not have a droppable class attribute are not zones. <table> <tbody> <tr> <td><img id="banner" class="droppable" alt="whatchamacallit"/></td> </tr> <tr> <td> <ul class="nav"> <li>page 1 </li> <li>page 2 </li> <li>page 3 </li> </ul> <img id="ad1" class="droppable" alt="ad1"/> </td> <td valign="top"> <div id="body"> <p>lorem ipsum dolor sit amet, consectetur adipiscing elit. </p> </div> </td> <td> <img id="ad2" class="droppable" alt="ad2"/> <img id="ad3" alt="ad3"/> </td> </tr> </tbody> </table> Use text in each zone to indicate the intended purpose of the area. When a zone contains text, it is visible to users and they can drag content onto the zone. 6 IBM Marketing Center Template and Web Developer Guide

11 When a zone does not have a text label, users must select the Show Zones option before they can drag content onto the zone. Providing a text label prevents possible confusion for the marketers who use your templates. For example, if your template is designed to communicate a monthly offer, you can name the zone Monthly Offer. <span id="monthly_offer" class="droppable">monthly Offer</span> <br/> Coding templates for text-only messages If your marketers must provide text-only version of their messages, you have two choices. You can create text-only templates for them to use. Or, you can tell them to have IBM Marketing Center generate a text-only version that is based on the template for the HTML version. If you want to create zones in a template for a text-only , the template must be in HTML format. Make sure the template uses the.html file extension if you are implementing zones. However, you are restricted to the following limited set of tags: v <html> and <body> tags that define the page v <span> tags with the droppable attribute set for zones v <br /> tag for line breaks v <UAEreferenceLabel> to include a digital asset For example, here is a simple, text-only template that has zones: <html> <body> Dear <span id="first_name" class="droppable">first name</span> <span id="last_name" class="droppable">last name</span>, <br/> Thank you for attending our recent conference. To show our appreciation for your interest, we will be sending you a gift autographed by our keynote speaker. <br/> We look forward to seeing you at future events soon. </body> </html> Coding the static sections The parts of your templates that are not zones are static sections. You code static sections as usual, that is, with XHTML-compliant code. Using content that is stored outside Marketing Center Use the <UAEConnect> tag to include text or HTML content that is stored outside Marketing Center in a static section of your template. For example, you can include text or HTML content from a web page. The system updates this content when the message is sent. Use <UAEConnect n="source path"/> where source path is the URL or path to the file that provides the content. Chapter 2. Creating templates 7

12 Note: You can connect to external content via HTTP or FTP, but you cannot connect to content that requires authentication (HTTPS or FTPS) at this time. To request an FTP server account for use with content connections, contact IBM Support. Note: Content connections are only for use with HTML snippets. You cannot use <head>, <html>, <body>, or<cdata> tags in any content that will be used as a content connection. You can include images and scripts in the static sections without using the <UAEConnect> tag. Images and scripts in the static sections must be accessible through HTTP and can also be accessed securely via HTTPS, when appropriate. You must use absolute paths to images, scripts, and URLs in the static sections of your templates. Ensure that the URL of the communication that is generated from the template and the URLs to the images or scripts in the static sections of that communication share a top-level domain name. If they do not, the message recipient's browser might display cross-domain warning messages when it displays the communication. For example, say the domain name that is managed for you by Marketing Center is .yourcompany.com and your images and scripts are accessed through yourcompany.com. In this case, both the communication and the URLs share a common top-level domain and the communication would not trigger any browser warnings. Using content that is stored in Marketing Center Use the <UAEreferenceLabel> tag to include content that is stored in Marketing Center in a static section of your template. For example, you can use a reference label to include a legal notice in your templates. When the legal notice must change, it can be updated in Marketing Center and affect all communications that are based on those templates. Changes show up in communications the next time their campaigns are built and deployed. The content must be stored as a digital asset in Marketing Center and must have a reference label. You must know the exact reference label for each asset you want to include. Use <UAEreferenceLabel n="name"/> where name is the value of the Reference Label field for the asset in Marketing Center. Including personalizations in templates Use the personalization field tag, <UAEpf>, to include personalized data in your template. A personalization field is a field that can contain personalized data, such as customer engagement data, data collected from tags, or data external to Marketing Center. You can use the <UAEpf> tag to save time if you are using many different personalization fields in an . Do not nest <UAEpf> tags. All <UAEpf> tags take a single attribute, n, which equals the Field ID. All fields are case sensitive. 8 IBM Marketing Center Template and Web Developer Guide

13 Standard Data Marketing Center includes the standard registration fields in the table below. <UAEpf n="age" /> Table 2. Standard Registration Fields Field ID REGISTRATION_ID _ADDRESS REGISTERED_CITY REGISTERED_STATE REGISTERED_COUNTRY REGISTERED_ZIP_CODE Associated information Registration ID address City State Country Zip code Customer Engagement Data To locate the field ID, navigate to the Manage Fields screen and look in the Field ID column. <UAEpf n="customer_engagement_data_field" /> Tagged Data To locate the field ID for tagged data, <UAEpf n="tag_data_1" /> Import Data Contact Support to obtain the field IDs if you need to use fields imported using IBM Digital Analytics Import. <UAEpf n="registration_rpt_attribute16 REGISTRATION" /> External Data You can only use external fields in transactional templates or assets. If you use an external field in a regular template or asset, the campaign will fail to build. <UAEpf n="externalfield" /> Including personalized images in a transactional template You can include a personalized image, such as a ticket bar code or a QR code, in a transactional . Define an image label in the template at the place where you want the image to be inserted. About this task Personalized images are sent as attachments, but they are displayed as images embedded in the body of the . Because the image is sent as an attachment, the recipient sees the image in the even if the client is configured to turn off images. The image label is case-sensitive. Chapter 2. Creating templates 9

14 Procedure 1. Open the template in an HTML editor. 2. Find the location where you want the image. 3. Decide whether you want the image to be a link. 4. Insert the image with one of the following tags. v Use an image tag for an image that is not a link: v <img src="#include:image_label#" alt="alt_text_for_image" border="0" /> Replace image_label with a unique name to identify the image. Provide alternative text for the image. Use an href tag for an image that is a link: <a href="link_target"><img src="#include:image_label#" alt="alt_text_for_link" border="0" /></a> Replace image_label with a unique name to identify the image. The target URL is the value for link_target. Provide alternative text for the image. Example Design for deliverability Here is an example of an image that is not a link: <img src="#include:barcode1#" alt="label for personalized image" border="0" /> Here is an example of an image that is a link: <a href=" src="#include:picture1#" alt="link to website" border="0" /></a> Deliverability measures your ability to consistently deliver marketing to the intended recipient's inbox. deliverability can be affected by many factors such as spam filters, blacklists, and bad addresses. When you design templates, include standardized items that ensure that each message generated from the template complies with anti-spam regulations. Also, include elements that generate confidence in your brand. Common methods to improve the deliverability of your include the following practices. v Include a zone that is designed to provide an opt-out or unsubscribe link. v If your company can accommodate more opt-out options (web-based, telephone, reply to ), include standardized text that describes how to do so. v Include a phrase that clearly identifies the as an advertisement. Some companies include that phrase in the unsubscribe statement at the bottom of an . For example, "This advertisement was sent to [ address of the recipient]. If you no longer want to receive these messages, click here to unsubscribe." v Provide a valid physical mailing address for recipients to identify or use to contact the company. v Include a standard sentence that requests that recipients add the From address from the message to their address books. v Put your brand logo in the same place in every from your company. v Do not use a single image that covers the entire message. 10 IBM Marketing Center Template and Web Developer Guide

15 For more information about CAN-SPAM, see the official Federal Trade Commission (FTC) website, specifically the page The CAN-SPAM Act: A Compliance Guide for Business. Uploading and testing the template After you code and validate a template, import it into IBM Marketing Center and test it before you tell marketers to use it. Procedure 1. In the Digital Assets section of the side navigation pane, click Actions > Import Asset and upload the template. Select the Is template check box. 2. Create an communication and select the new template. 3. Click the Show zones check box and select All. Does everything look correct? It is common to see something you must fix only after you upload a template and use it to create a communication. 4. For small code fixes, click the Edit Template icon ( ) and make your edits. 5. If you need to make major changes, it is best to return to your own third-party HTML editor. Then upload the revised HTML file into the digital assets library. 6. If you upload a new version of a template with the same file name, you must refresh the communication in some way before you see your changes. For example, you can close it and reopen it or you can add the template again. Results When you are sure that your template code works properly, tell the marketers that they can start using it. Chapter 2. Creating templates 11

16 12 IBM Marketing Center Template and Web Developer Guide

17 Chapter 3. Preparing your site for Marketing Center To integrate your company's website Marketing Center, you must first tag your site. The Digital Analytics Implementation Guide describes how to add the JavaScript necessary to integrate your site with Marketing Center If a web page is tagged with multiple client IDs A web page can be modified by site communications from one client ID only. If a page is tagged with multiple client IDs, you must create all site communications for that page in the first client ID listed in the cmsetclientid function. You can change the order of client IDs in the cmsetclientid function if needed, but changing the order might break other communications in IBM Marketing Center and recommendations in IBM Digital Recommendations. Configure elements for website personalizations Any element on your web page that has a value for the ID attribute or has a parent element with an ID attribute is customizable. For example, the following code snippet defines two zones: 1 <span id="center_content1" >Zone #1</span> 2 <div id="center_content2" ><span class="ctr">zone #2</span></div> Be sure you have defined an ID for each element you want to customize. Give each element a unique, descriptive, and memorable definition. Later, you can use your program's search function to locate the ID if you need to modify it. When marketers create a site communication for a page that contains that code, each zone is marked with a pushpin icon. Always provide default content for zones, for example, a brand image or text. That way you prevent broken images and placeholder text if there is a network or other connection failure. Do not nest elements that you intend to personalize. Nesting elements can cause outer elements to override inner elements. How JavaScript is loaded into your web pages Digital Analytics page tags and Marketing Center site communications work by using JavaScript files. The JavaScript files are loaded to your web pages from the content delivery network (CDN). When you create your web page, include this call in each page: <script src=" type="text/ javascript"> Copyright IBM Corp. 2009,

18 This JavaScript file, eluminate.js, runs synchronously. After eluminate.js completes, the remaining JavaScript files are loaded asynchronously to minimize load time. Refer to the Digital Analytics Implementation Guide for information about using eluminate.js in your website. The following flowchart demonstrates the loading sequence. Refer to the following table for a description of each file. Table 3. JavaScript load sequence JavaScript Description Example Size eluminate.js The Digital Analytics tag container library. This file is common for all client IDs. <script src=" libs.coremetrics.com/ eluminate.js"> ~148 kb <client-id>.js mc.js Product configuration bitmap that indicates which Digital Analytics applications are enabled. This file is unique for each client ID. Marketing Center bootstrap logic to apply site communications. This file is common for all client IDs. <script src=" libs.coremetrics.com/ configs/ js"> <script src=" libs.coremetrics.com/ mc.js"> ~100 b ~27 kb 14 IBM Marketing Center Template and Web Developer Guide

19 Table 3. JavaScript load sequence (continued) JavaScript Description Example Size rules-<client-id>.js JSON content that determines if the current page has an active campaign. It also defines conditions and segments and provides a map to the treatment file. This file is unique for each client ID. <script src=" mktgcdn.coremetrics.com/ /JS/rules js"> ~18.4 kb Size depends on the rule definitions. treatment- <treatment-id>.js JSON content that contains instructions on how to apply a treatment from content on the CDN. This file is unique for each treatment. <script src=" mktgcdn.coremetrics.com/ /JS/treatment js"> ~2.6 kb Chapter 3. Preparing your site for Marketing Center 15

20 16 IBM Marketing Center Template and Web Developer Guide

21 Chapter 4. Enabling users to opt-out of communications You can configure an opt-out page so that your users have a way to stop Marketing Center communications. Use the opt-out page to comply with privacy policies that require you to provide a way for customers to opt out of communications. There are two ways to implement the opt-out page: v Use the standard opt-out page that is fully hosted on the content delivery network (CDN). You can use the opt-out page directly or load it within a frame on your site. This method requires no additional coding on your site. You need only to create a link to a URL. v Code your own opt-out page and pass the information by using an HTTP GET request to a servlet on IBM servers. This method requires coding, but enables you to tightly integrate the opt-out functionality with your website. Using the standard CDN-hosted opt-out page The easiest way to implement the opt-out page is to use the reference page that is hosted on the CDN. It requires only a hyperlink to a page on the CDN and no additional code on your page. You can also load the opt-out page into an iframe on your page. About this task Following is an example of the standard opt-out page. Copyright IBM Corp. 2009,