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

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. WebLogic Portal 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 WebLogic Portal, refer to "Creating and Managing Content" in the Guide to Building Personalized Applications.

Loading Ads into the Reference Content Management System

WebLogic Portal 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 WebLogic Portal, 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 "Deploying Your Business Data" in 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:

PORTAL_HOME/dmsBase/Ads

where PORTAL_HOME is the directory in which you installed WebLogic Portal.

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:

PORTAL_HOME\bin\win32\loadads.bat (Windows)
PORTAL_HOME/bin/unix/loadads.sh (UNIX)

where PORTAL_HOME is the directory in which you installed WebLogic Portal.

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 Microsoft 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:

• Create and Compile a Java Class to Generate HTML

• Register the New Class

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 com.bea.p13n.ad.AdContentProvider interface. For information on this interface, refer to WebLogic Portal Javadoc.

After you compile the class, you must make sure the class is available to the application. One way to do this is to add the class appropriately to one of the deployed jar files, such as placeholder.jar or your own jar file. Another way to make the class available to the application is to save it under a directory that is specified in the system's CLASSPATH environment variable. For example, create a WL_PORTAL_HOME/classes directory and add it to the set-environment script. 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

After you save the class in a directory that is in your classpath, you must notify WebLogic Portal of its existence:

1. Stop the WebLogic Portal instance that is running your application. For information on stopping a server, refer to "Starting and Shutting Down a Server" in the Deployment Guide.

2. Create a backup copy of PORTAL_HOME/application/your-application/META-INF/application-config.xml

3. Open application-config.xml in a text editor and find the <AdService> element.

4. Add the following as a subelement of <AdService>:

   <AdContentProvider
   Name="MIME-type"
   Provider="name-of-your-class"
   Properties="optional-properties-for-your-class"
   >
   </AdContentProvider>

   Provide the following values for the attributes of the AdContentProvider element:

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

   • Provider. 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.

   • Properties. Any additional properties or parameters want to pass to your object.

     For example, if you added WL_PORTAL_HOME/classes to the system classpath, save your class to support AVI files as WL_PORTAL_HOME/classes/myclasses/MimeAvi.class.

     Alternately, if you have already deployed a JAR of your own Java classes called myServices.jar, add myclasses/MimeAvi.class to that JAR file.

     To register your classname, add a subelement to the AdService element as illustrated in Listing 2-3.

     Listing 2-3 Add An AdContentProvider Element

     <AdService
           Name="wlcsApp"
           DisplayFlushSize="10"
           Rendering="com.bea.p13n.ad.AdContentProviderBase"
           EventTracker="com.bea.campaign.AdTracking"
           AdClickThruURI="AdClickThru"
           ShowDocURI="ShowDoc"
         >

           <AdContentProvider
             Name="text"
             Provider="com.bea.p13n.ad.render.TextContentProvider"
             Properties=""
           >
           </AdContentProvider>

           <AdContentProvider
             Name="image"
             Provider="com.bea.p13n.ad.render.ImageContentProvider"
             Properties="AdClickThruURI=AdClickThru;ShowDocURI=ShowDoc"
           >
           </AdContentProvider>

           <AdContentProvider
             Name="application/x-shockwave-flash"
             Provider="com.bea.p13n.ad.render.ShockwaveContentProvider"
             Properties="ShowDocURI=ShowDoc"
           >
           </AdContentProvider>

           <AdContentProvider
             Name="video/x-msvideo"
             Provider="myclasses.MimeAvi"
             Properties=""
           >
           </AdContentProvider>

       </AdService>

5. Save your modifications to application-config.xml.

6. Restart WebLogic Portal.