Setting Up Ads for Campaigns

 

An ad is a document in your content management system that an ad placeholder displays. Ads can be an integral part to a campaign. For example, campaigns can specify as a goal to record a specific number of ad clickthroughs.

This topic includes the following sections:

• Describing the Ads in Your Content Management System

• Specifying Display and Clickthrough Behavior

• Loading Ads Into Your Content Management System

• Supporting Additional MIME Types

• Tip: Clearing Scenario Queries from an Ad Placeholder

For more information about ads, refer to "Working with Ad Placeholders" in the Guide to Building Personalized Applications.

 

---

Describing the Ads in Your Content Management System

The queries that a BA defines for ad placeholders search through the descriptions (attributes) that you attach to the documents in your content management system. Campaign Manager for WebLogic places no restrictions on the set of attributes that you use to describe your ads. For example, you can create attributes that describe the name of the product that the document advertises, the name of the ad sponsor, and a product category that matches the categories in your e-commerce product catalog.

We recommend that a BA analyses your advertising strategy and proposes a set of attributes that describe the ads in your content management system.

For information on adding attributes, refer to the documentation for your content management system. If you use the reference content management system, refer to Loading Ads into the Reference Content Management System.

 

---

Specifying Display and Clickthrough Behavior

Ad placeholders use a set of document attributes that you define in your content management system to support the following features:

• Choosing a single document if a query returns multiple documents

• Making an image ad clickable

• Supplying movie preferences for a Shockwave file

For information about associating attributes with documents, refer to the documentation for your content management system. If you use the reference content management system, refer to Loading Ads into the Reference Content Management System.

Table 2-1 describes the adWeight attribute, which you can associate with XHTML, image, and Shockwave documents.

Table 2-1 Attributes for All Document Types

Attribute Name	Value Type	Description and Recommendations
adWeight	Integer	Provides an integer that is used to select a document if a query returns multiple documents. Assign a high number to ads that you want to have a greater chance of being selected. For more information, refer to "How an Ad Placeholder Chooses from Ad Query Results" under "Working with Ad Placeholders" in the Guide to Building Personalized Applications. The default value for this attribute is 1. Note: In the E-Business Control Center, you can assign a priority to a query for a scenario action. The priority, which bears no relation to the adWeight attribute, gives a greater or lesser chance that a placeholder runs a query. The adWeight attribute is used to choose an ad after a query has run. For more information, refer to "How the Ad Conflict Resolver Chooses a Query" under "Working with Ad Placeholders" in the Guide to Building Personalized Applications.

 

Table 2-2 describes attributes in addition to the adWeight attribute that you can associate with image files.

Table 2-2 Attributes for Image Files

Attribute Name	Value Type	Description and Recommendations
adTargetUrl	String	Makes an image clickable and provides a target for the clickthrough, expressed as a URL. The Event Service records the clickthrough. Use either adTargetUrl, adTargetContent, or adMapName, depending on how you want to identify the destination of the ad clickthrough.
adTargetContent	String	Makes an image clickable and provides a target for the clickthrough, expressed as the content management system's content ID. The Event Service records the clickthrough. Use either adTargetUrl, adTargetContent, or adMapName, depending on how you want to identify the destination of the ad clickthrough.
adMapName	String	Makes an image clickable, using an image map to specify one or more targets. The value for this attribute is used in two locations: In the anchor tag that makes the image clickable, <a href=value> <img> </a> In the map definition, <map name=value> Use either adTargetUrl, adTargetContent, or adMapName, depending on how you want to identify the destination of the ad clickthrough. If you specify a value for adMapName, you must also specify a value for adMap.
adMap	String	Supplies the XHTML definition of an image map. If you specify a value for adMap, you must also specify a value for adMapName.
adWinTarget	String	Displays the target in a new pop-up window, using JavaScript to define the pop-up. The only value supported for this attribute is newwindow.
adWinClose	String	Specifies the name of a link that closes a pop-up window. The link appears at the end of the window content. For example, if you provide "Close this window" as the value for this attribute, then "Close this window" appears as a hyperlink in the last line of the pop-up window. If a customer clicks the link, the window closes.
adAltText	String	Specifies a text string for the alt attribute of the <img> tag. If you do not include this attribute, the <img> tag does not specify an alt attribute.
adBorder	Integer	Specifies the value for the border attribute of the <img> tag. If you do not include this attribute, the border attribute is given a value of "0".

 

Table 2-3 describes attributes in addition to the adWeight attribute that you can associate with Shockwave files. Ad placeholders and the <ad:adTarget> tag format these values as attributes of the <OBJECT> tag, which Internet Explorer on Windows uses to display the file, and the <EMBED> tag, which browsers that support the Netscape-compatible plug-in use to display the file.

For more information about these attributes, refer to your Shockwave developer documentation.

Table 2-3 Attributes for Shockwave Files

Attribute Name	Value Type	Description and Recommendations
swfLoop	String	Specifies whether the movie repeats indefinitely (true) or stops when it reaches the last frame (false). Valid values are true or false. If you do not define this attribute, the default value is true.
swfQuality	String	Determines the quality of visual image. Lower qualities can result in faster playback times, depending on the client's Internet connection. Valid values are low, high, autolow, autohigh, best.
swfPlay	String	Specifies whether the movie begins playing immediately on loading in the browser. Valid values are true or false. If you do not define this attribute, the default value is true.
swfBGColor	String	Specifies the background color of the movie. This attribute does not affect the background color of the HTML page. Valid value syntax is #RRGGBB.
swfScale	String	Determines the dimensions of the movie in relation to the area that the HTML page defines for the movie. Valid values are showall, noborder, exact fit.
swfAlign	String	Determines whether the movie aligns with the center, left, top, right, or bottom of the browser window. If you do not specify a value, the movie is aligned in the center of the browser. Valid values are l, t, r, b.
swfSAlign	String	Determines the movie's alignment in relation to the browser window. Valid values are l, t, r, b, tl, tr, bl, br.
swfBase	String	Specifies the directory or URL used to resolve relative pathnames in the movie. Valid values are .(period), directory-name, URL.
swfMenu	String	Determines whether the movie player displays the full menu. Valid values are true or false.

 

---

Loading Ads Into Your Content Management System

This section contains the following subsections:

• Loading Ads into a Third-Party Content Management System

• Loading Ads into the Reference Content Management System

Loading Ads into a Third-Party Content Management System

You use the same procedure for loading ads into your content management system as you use for loading any other document. For information on loading documents, refer to the documentation for your content management system.

For more information about using a content management system with Campaign Manager for WebLogic, refer to "Creating and Managing Content" in the Guide to Building Personalized Applications.

Loading Ads into the Reference Content Management System

Campaign Manager for WebLogic provides a content management system for sites with limited content-management needs. If you use the reference content management system, you must load ads and ad attributes at the same time. You cannot add attributes to documents that have already been loaded.

When you install Campaign Manager for WebLogic, the reference content management system (which uses the sample Cloudscape database) already contains a set of sample ads. If you set up other supported databases, refer to the Deployment Guide, which describes using the loadSampleData script to populate your database and the reference content management system with sample data. This section describes loading ads into the reference management system in addition to any ads that you loaded into the system using the loadSampleData script.

Note: The reference content management system requires different processes for loading ads and loading other documents that you do not use as advertisements. This section describes only the process of loading ads. For information on loading other documents, refer to "Creating and Managing Content" in the Guide to Building Personalized Applications.

To load ads and ad attributes into the reference content management system, you must do the following:

• Set Up Attributes in HTML Documents

• Set Up Attribute Files for Image and Shockwave Documents

• Move Files Into the dmsBase/Ads Directory Tree

• Run the loadads Script

Set Up Attributes in HTML Documents

For ads that contain only HTML, you must place document attributes in <META> tags within a document's <HEAD> element. Use the following syntax in the <META> tag:

<META name=attribute-name content=attribute-value>

Use a separate <META> tag for each document attribute. For example:

<META name=attribute1-name content=attribute1-value>
<META name=attribute2-name content=attribute2-value>
<META name=attribute3-name content=attribute3-value>

Listing 2-1 shows an HTML file that contains a simple ad with several attributes.

Listing 2-1 Attributes for an HTML Ad

<HTML>
<HEAD>

<META name=adWeight content=3>
<META name=productCategory content=hardware>
<META name=productSubCategory content=electic drill>
<META name=productName content=Super Drill>
<META name=Manufacturer content=ACME>

</HEAD>

<BODY>

<P>Buy our Super Drill. It'll get the job done!</P>

</BODY>

</HTML>

Set Up Attribute Files for Image and Shockwave Documents

For ads that are images or Shockwave movies, you must place attributes in a separate file. Each image or Shockwave file must be accompanied by a separate file that is named with the following convention:

filename.extension.md.properties

Both files must be located in the same directory.

For example, for an image file named superDrill.jpg, you must place attributes in a file named superDrill.jpg.md.properties.

Within the filename.extension.md.properties file, use the following syntax to express attributes and values:

attribute-name=attribute-value

Listing 2-2 shows an example file that contains attributes for an image ad.

Listing 2-2 Syntax for the Attributes File

adWeight=5
adTargetUrl="AcmeAds/saws.jpg"
adAltText=Buy ACME and save!

productCategory=hardware
productSubCategory=electic drill
productName=Super Drill
Manufacturer=ACME

Move Files Into the dmsBase/Ads Directory Tree

All HTML, image, and Shockwave files, and all attributes files must be located below the following directory:

WL_COMMERCE_HOME/dmsBase/Ads

where WL_COMMERCE_HOME is the directory in which you installed Campaign Manager for WebLogic.

You can place documents in subdirectories of the Ads directory, though the reference content management system does not use the subdirectories to organize documents.

If you use subdirectories to manage your source files, you must place the attributes files in the same directory as the files that they describe. For example, superDrill.jpg and superDrill.jpg.md.properties must be in the same directory.

Run the loadads Script

The loadads script loads documents from the dmsBase/Ads directory to the content management system. It also attaches attributes to the documents.

The pathname for the script is as follows:

WL_COMMERCE_HOME\bin\win32\loadads.bat (Windows)
WL_COMMERCE_HOME/bin/UNIX-platform-type/loadads.sh (UNIX)

where WL_COMMERCE_HOME is the directory in which you installed Campaign Manager for WebLogic.

For more information on loading documents into the reference content management system, refer to "Creating and Managing Content" in the Guide to Building Personalized Applications.

 

---

Supporting Additional MIME Types

To display an ad, placeholders refer to a document's MIME type and then generate the HTML tags that a browser requires for the specific document type. For example, to display an image-type document, an ad placeholder must generate the <img> tag that a browser requires for images. By default, ad placeholders can generate the appropriate HTML only for the following MIME types:

• XHTML (a fragment or an entire document). For this type of document, a placeholder passes the text directly to the JSP.

• Images. For this type of document, a placeholder generates an <img> tag with attributes that the browser needs to display the image. If you want images to be clickable, you must specify the target URL and other link-related information as ad attributes in your content management system.

• Shockwave files. For this type of document, a placeholder generates the <OBJECT> tag, which Internet Explorer on Windows uses to display the file, and the <EMBED> tag, which browsers that support the Netscape-compatible plug-in use to display the file. In your content management system, you can specify attributes for the <OBJECT> and <EMBED> tags.

If you are familiar with basic Java programming, you can write classes that enable placeholders to generate HTML for additional MIME types. To support additional MIME types, you must complete the following tasks:

• Add the New Type to the Deployment Descriptor

• Create and Compile a Java Class to Generate HTML

• Register the New Class in weblogiccommerce.properties

Add the New Type to the Deployment Descriptor

Each Campaign Manager for WebLogic Web application must specify its deployment requirements in an XML file called a deployment descriptor. To add a new MIME type for ad placeholders, you must modify the deployment descriptor for your WebLogic Personalization Server Web application. You can use a text editor to modify the deployment descriptor.

If you use the example portal as a framework for developing your own Web application, then the deployment descriptor is located at the following pathname:

WL_COMMERCE_HOME/config/wlcsDomain/applications/wlcsApp/exampleportal/WEB-INF/web.xml

where WL_COMMERCE_HOME is the location in which you installed Campaign Manager for WebLogic. Your Web application might be in another location. Contact your Campaign Manager for WebLogic administrator for information on which deployment descriptor to modify.

The deployment descriptor for your WebLogic Personalization Server Web application already contains a set of mappings for MIME type. Before you add a new type, review the existing mappings. Listing 2-3 illustrates a single MIME mapping from the example portal's deployment descriptor.

Listing 2-3 MIME Mapping in exampleportal/WEB-INF/web.xml

<mime-mapping>

    <extension>
      jpeg
    </extension>

    <mime-type>
      image/jpeg
    </mime-type>

</mime-mapping>

To add a new mapping, use the following syntax:

<mime-mapping>

    <extension>
      file-extension
    </extension>

    <mime-type>
      type/subtype
    </mime-type>

</mime-mapping>

where file-extension is the extension of the file type you want to map and type/subtype is a recognized MIME type and subtype.

Make sure that you provide end-tags for each of the XML elements.

When you save the modified deployment descriptor, you must restart the server to deploy the modifications. However, we recommend that you do not restart the server until you have registered the new Java class in weblogiccommerce.properties as described in Register the New Class in weblogiccommerce.properties.

Create and Compile a Java Class to Generate HTML

To generate the HTML that the browser requires to display the MIME type, create and compile a Java class that implements the bea/commerce/platform/ad/AdContentProvider interface. For information on the bea/commerce/platform/ad/AdContentProvider interface, refer to Campaign Manager for WebLogic Javadoc.

After you compile the class, you must save it in or below a directory that is specified in the system's CLASSPATH environment variable. For example WL_COMMERCE_HOME/classes is in the classpath. For more information about the CLASSPATH environment variable, refer to "Setting Environment Variables," under "Starting and Shutting Down the Server" in the Deployment Guide.

Register the New Class in weblogiccommerce.properties

After you save the class in a directory that is in your classpath, you must notify Campaign Manager for WebLogic of its existence and purpose by adding a line to weblogiccommerce.properties. You can use a text editor to modify this file, which is located at the following pathname:

WL_COMMERCE_HOME/weblogiccommerce.properties

where WL_COMMERCE_HOME is the location in which you installed Campaign Manager for WebLogic.

To register your new class in the weblogiccommerce.properties file, find the section that Listing 2-4 illustrates. Then add a line that conforms to the following syntax:

adtargettag.rendering.mime-type.mime-extension=your-classname

Provide the following values for the variables in the previous syntax statement:

• mime-type. The name of the MIME type that you want to support.

• mime-extension. The filename extension that Campaign Manager for WebLogic uses to associate the file with the MIME type.

• your-classname. The name of the compiled Java file. If you saved the file below a directory that your CLASSPATH environment variable names, you must include the file's pathname, starting one directory level below the directory in classpath.

For example, WL_COMMERCE_HOME/classes is in the classpath. You saved your class to support AVI files as
WL_COMMERCE_HOME/classes/myclasses/MimeAvi.class
To register your classname, add the following line to weblogiccommerce.properties:

adtargettag.rendering.video.avi=myclasses.MimeAvi

Listing 2-4 Rendering Classes in weblogiccommerce.properties

###############################################
# AdTargetTag Properties

adtargettag.rendering=com.bea.commerce.platform.ad.AdClickThruServlet
# This is the class that implements the AdEventTracker interface
# and is used to raise events
adtargettag.eventtracking=com.bea.commerce.campaign.AdTracking

# Additional classes to render content based upon mime type
# To use replace the "text.html" with the mime type, replacing any
# '/' characters with '.'
# Place the name of the java class that handles the mime type after the '='

#adtargettag.rendering.text.html=

 

---

Tip: Clearing Scenario Queries from an Ad Placeholder

In the E-Business Control Center, a BA can create a scenario action that places a query in a specific ad placeholder when an event or some other state triggers the scenario.

Campaign Manager for WebLogic uses a table to keep track of which scenario-specific queries in a placeholder apply to which customer IDs. For example, if Pat Gomes triggers a scenario to place a query in the top-banner placeholder, Campaign Manager for WebLogic stores the Pat Gomes/top-banner-placeholder/scenario-query association in a table in its data repository.

Once a scenario places a query in a placeholder for a specific user, Campaign Manager for WebLogic persists the information until any of the following occurs:

• The campaign achieves its goal for running the scenario query and displaying the corresponding ad.

• The campaign ends because it has achieved some other goal, the end date/time for the campaign has arrived, or a BA ends the campaign in the E-Business Control Center.

• An event or system state triggers another action for the scenario (or re-triggers the same action) that placed the query in the placeholder.

  Scenarios can contain multiple actions that place queries in one or more placeholders under different conditions. For example, when Pat Gomes logs in, scenario1 can place queryA in the top-banner placeholder. When Pat Gomes adds a drill to the shopping cart, scenario1 can place queryB in the top-banner placeholder. However, when a scenario engages a scenario action, it can place only one query in a placeholder for a given customer, and the query remains in the placeholder until the scenario replaces it. For example, when Pat Gomes adds a drill to the shopping cart, scenario1 replaces its queryA with queryB.

• The date/time that you specify in the Select Duration window in the E-Business Control Center has expired.

  The Select Duration window is available for any queries that you create after you install Service Pack 1 or later of Campaign Manager for WebLogic, WebLogic Commerce Server, and WebLogic Personalization Server. You access the window as part of creating a query for an ad placeholder. From the New Ad Action window, under Action, click the "until the campaign ends" link. (See Figure 2-1.)

  Figure 2-1 Accessing the Select Duration Window

  
   

In the Select Duration window, indicate whether you want the query to stop running before the campaign ends by selecting a timeframe or date. (See Figure 2-2.)

Figure 2-2 The Select Duration Window

 

Because of the persistence mechanism, some actions might leave a scenario query stranded in a placeholder for a specific user, even across multiple sessions on the Web site.

For example:

• After a scenario action places a query in the top-banner placeholder for Pat Gomes, a BA deletes the scenario action. Deleting the scenario action does not clear the query from the placeholder. Only another action from the same scenario can replace the query. Instead of deleting the scenario or scenario action, we recommend that you modify the scenario action to place default queries in the placeholder. Then, when the scenario action is triggered, it replaces the campaign-specific query with a generic, default ad query. (A BA defines default queries in the Ad Placeholder Editor, which is part of the E-Business Control Center.)

• Pat Gomes places a drill in the shopping cart and triggers a scenario action to place a query in a shopping-cart placeholder. If Pat Gomes removes the drill from the shopping cart, the scenario action does not remove its query from the shopping-cart placeholder. Only another action from the same scenario can replace the query. For example, along with the action that places a query in the shopping-cart placeholder when a user adds a drill to the shopping cart, you can create an action for the same scenario that places default queries in the shopping-cart placeholder when a user removes a drill from the shopping cart.

In general, we recommend that for each scenario that includes an ad-placeholder action, you include an additional scenario action that does the following:

• When a user logs in, display default queries in the same ad placeholder.

This scenario action clears the placeholder from any campaign-specific ad queries each time a customer logs on to the site.