Skip Headers
Oracle® Communications Marketing and Advertising Integration Guide
Release 5.1
Part Number E20559-01
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

5 Using Oracle Communications Marketing and Advertising as an Ad Server

Oracle Communications Marketing and Advertising can serve ad content to external applications when acting as an Open Mobile Alliance (OMA) Ad Server over web services. MobAd-compliant content stored in Marketing and Advertising can be retrieved and displayed through various channels in OMA Mobile Advertising v1.0 compliant format. For more information on the OMA and Mob Ad see:

http://www.openmobilealliance.org/Technical/release_program/mobad_v1_0.aspx

Overview

There are many types of applications that integrate with ad servers for targeted advertising. Examples of such applications can include ad-aware content applications or downloadable applications or games.

Marketing and Advertising can be configured to accept MobAd ad requests, return ad content and manage campaigns associated with external entities. Statistical information from external applications/entities about served OMA ads can also be collected by Marketing and Advertising for reporting purposes.

The Ad Server functionality provided by Marketing and Advertising is web service based. To setup an integration of an external application with the Ad Server Web Service you should review the following Web Service information and sample campaign configuration steps:

  1. Understanding the Ad Server Web Service

  2. Marketing and Advertising Ad Server Processes

Understanding the Ad Server Web Service

The Marketing and Advertising Ad Server API is web service based utilizing SOAP transmission over HTTP 1.1 protocol. The WSDL provided by the Ad Server web service is based on the OMA MobAd specification XSD/draft specfication. As the specification is subject to change be sure to verify compatibility between OMA MobAd version and the Marketing and Advertising release version.

Errors

Errors are returned in a SOAP Message that includes a human readable faultstring element that describes the error. Table 5-1 contains a list of fault codes associated with the Ad Server web service.

Table 5-1 Ad Server Error Codes

Error Code Description

OCMA-1022

A validation exception occurred for field field

OCMA-1049

Failed to load DAO object id=objectID, class=classID

OCMA-1053

The user user is not allowed to execute operation operation on entity

OCMA-1058

Failed to load image

OCMA-1060

Invalid parameter parameter for entity

OCMA-1070

Attribute not supported

OCMA-1077

Banner image type error

Data Structures Used in the Web Service

The following data structures appear in the web service.

SPAppAdRequestInfo

This elements in Table 5-2 represent the actual request for an ad. Although the xsd allows an unbounded list of these elements to retrieve multiple ads per a single request, the current implementation allows only one of these elements per request.

Table 5-2 SPAppAdRequestInfo Complex Type

Parameter XML Type Data Type Cardinality Comments

AdUnit

Attribute

xs:string

0...1

Not supported

ProvideAdContent

Attribute

xs:boolean

0..1

If FALSE, the type of ad returned is URL Content. TRUE for other ad types

It is always supported to omit this parameter (provide NULL)

AdValidity

Attribute

xs:string

0..1

Not supported

ContextuaData

Sub-element

mobad:ContextualDataType

0..N

Not supported

SPAppProvidedAd

This elements in Table 5-3 represent the entire returned ad.

Table 5-3 SPAppProvidedAd Complex Type

Parameter XML Type Data Type Cardinality Comments

AdContentData

Sub-element

See Table 5-4

1

The content of the returned ad

AdUsage

Sub-element

See Table 5-5

0..1

Contains only the FrequencyCap attribute set to "1"

AdID

Attribute

xs:string

0..1

"ocma" + campaignID (within the system)

Outdated-AdID

Attribute

xs:string

0..N

Not supported. Omitted in response

ContextualDataID

Attribute

mobad:ContextualDataID

0..1

Not supported. Omitted in response

AdType

Attribute

xs:integer

0..1

Not supported. Omitted in response

AdUnit

Attribute

mobad:AdUnit

0..1

Not supported. Omitted in response

AdContentData

This elements in Table 5-4 represent the content in the returned ad.

Table 5-4 AdContentData Complex Type

Parameter XML Type Data Type Cardinality Comments

MIME-Type

Attribute

xs:string

1

Indicates the mime-media type of the content. For URL Content, an empty string is returned

MIME-Version

Attribute

xs:string

0..1

Not supported. Omitted in response

AdWidth

Attribute

Ixs:integer

0..1

Not supported. Omitted in response

AdHeight

Attribute

xs:integer

0..1

Not supported. Omitted in response

AdDuration

Attribute

xs:integer

0..1

Not supported. Omitted in response

AdContentSize

Attribute

xs:integer

1

Indicates the size in bytes of the Ad payload. For URL Content, 0 is returned

TextEncoding

Attribute

xs:string

1, if used

Indicates the encoding scheme for text, such as Unicode or UTF-8. Used in cases where the MIME-Type is of type text

AdContentPayload

Sub-element

xs:hexBinary

1, if used

Contains the actual Ad content. Used in cases where content is not URL Content

AdLocationURI

Sub-element

xs:anyURI

1, if used

Contains the URI. Used in cases where content is URL Content

InteractivityAction

Sub-element

mobad:InteractivityActionType

0..N

Not supported. Omitted in response

AdUsage

This elements in Table 5-5 represent the number of times the ad is placed.

Table 5-5 AdUsage Complex Type

Parameter XML Type Data Type Cardinality Comments

DisplayTime

Attribute

xs:string

0..1

Not supported. Omitted in response

FrequencyCap

Attribute

xs:integer

0..1

Always 1.

PreserveAdFormat

Attribute

xs:boolean

0..1

Not supported. Omitted in response

AdValidity

Attribute

xs:string

0..1

Not supported. Omitted in response

AdMetricsData

This elements in Table 5-6 represent the campaign metrics for an ad.

Table 5-6 AdMetricsData Complex Type

Parameter XML Type Data Type Cardinality Comments

AdID

Attribute

mobad:AdID

1

Must be identical to AdID in Table 5-2. ocma + campaignID

MetricType

Attribute

xs:string

0..1

Must be either a or impression

MetricValue

Attribute

xs:string

0..1

The number of messages covered by this report. If omitted, assumed to be 1.

ViewDuration

Attribute

xs:integer

0..1

Not supported. Omitted in response

DisplayDateTime

Attribute

xs:dateTime

0..1

A timestamp on the statistic. For example, 2008-01-09+01:00

SpApp Ad Web Service

The SpApp Ad web service is made up of two operations. The first operation, SpAppAdRequest, requests an ad. The second operation, SPAppMetricsReport, allows the external entity to report that it has placed the ad, which increments the Ad Impression counter for statistical purposes.

Operations Provided by the Web Service

The two operations provided by the web service follow.

Operation:SPAppAdRequest

This operation represents an external application request for Marketing and Advertising hosted ad content data.

Table 5-7 describes the SPAppAdRequest operation.

Table 5-7 SPAppAdRequest Input Message

Parameter Name XML Type Data Type Cardinality Comments

SPAppAdRequestInfo

Element

See Table 5-2

1

Only a single ad can be requested at a time

Version

Attribute

mobad:Version

0..1

Based on the Mob-Ad specification

SPAppID

Attribute

mobad:SPAppID

1

Identical to the SPAppID used to create the OMA Server Connection Configuration

RequestUrgency

Attribute

mobad:RequestUrgency

0..1

Not supported

PrincipalID

Attribute

xs:string

0..1

Principal ID of the application making request

Table 5-8 table describes the SPAppAdResponse operation.

Table 5-8 SPAppAdResponse Output Message

Parameter Name XML Type Data Type Cardinality Comments

SPAppProvidedAd

Element

See Table 5-3

1

Only a single ad is provided at a time

Operation: SPAppMetricsReport

This operation allows an external application/entity to update Marketing and Advertising with campaign statistics, such as number of impressions, for the application/entity.

Table 5-9 describes the SPAppMetricsReport operation.

Table 5-9 SPAppMetricsReport Input Message

Parameter Name XML Type Data Type Cardinality Comments

SPAppID

Attribute

xs:string

1

Identical to the SPAppID used to create the OMA Server Connection Configuration

AdMetricsData

Element

See Table 5-6

1..N

The impression to be reported

Marketing and Advertising Ad Server Processes

OMA Ad Server campaigns in Marketing and Advertising follow the same general process flow as native ad campaigns. An external application requesting Marketing and Advertising ad content must have an associated Connection Configuration. A Network Provider creates this Connection Configuration which contains an application ID (SpAppID). External application operators act as Marketing and Advertising Ad Space Owners creating marketable Ad Spaces to sell to Advertisers.

In a production environment an external application submits a web service Mob-Ad request containing the identifying SpAppID to Marketing and Advertising. Marketing and Advertising uses this SpAppID to determine the proper ad content for the Ad Space purchased by advertisers. The retrieved ad content is returned in the web service response to the external application.

The following steps outline configuring Marketing and Advertising to process an external application ad request. For additional information on the Marketing and Advertising entities mentioned see . Additional information can also be found in the Online Help for the specified users.

  1. Understanding OMA Ad Server Concepts

  2. Creating an OMA Ad Server Connection Configuration

  3. Bidding and Purchasing OMA Ad Space

  4. Responding to External Application Requests Ad

  5. Reporting Ad Server Statistics

Understanding OMA Ad Server Concepts

Marketing and Advertising relies on the external OMA application requesting ad content to identify itself using an application identifier in order to determine the correct connection configuration assigned to the application. The connection configuration inherently contains channel information indicating what type of ad content can be used to fulfill the request. Marketing and Advertising supports text, URL and simple HTML snippet ad content for Mob-Ad requests.

OMA SP Application Identifier

In the context of the OMA specification, the SP Application is the external entity that is requesting ads from the Ad Server. For tracking purposes, an ID is assigned to this entity using this parameter. In effect, this identifier indicates a particular external space in which an ad might appear. It could be part of an existing HTML page; it could be a game engine on a mobile device, etc.

Channel Types

In Marketing and Advertising connection configurations, Channel Type refers to the type of traffic that will carry the ad message - SMS, MMS, or WAP Push. In an OMA connection configuration, only the ad itself is being provided, so the Channel Type simply defines the type of ad made available. There are three possible types:

  • Text: A text-only ad

  • URL: A URL to content hosted elsewhere on the Web: for example, an IP TV ad streaming from another site

  • Simple HTML Snippet: An ad that can contain text, a URL, and an image that is fetched from a servlet running within the system. The snippet is provided as hex code. See Example 5-1 and Example 5-2. The URL to the image is retrieved from the OCMA Web URL field in the General tab of the OCMA Administration console.

    Example 5-1 Example HTML Snippet

    <a href="http://SomeWebSite.com/">
 Buy This!
 <img src="http://localhost:8001/ocma/SnippetContent?segId=2&cId=126&rId=7693376823328250879"/>
</a>

    Example 5-2 Example HTML Snippet as Hex Code

    3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 53 6f 6d 65 57 65 62 53 69 74 65 2e 63 6f 6d 2f 22 3e 0d 0a 20 42 75 79 20 54 68 69 73 21 20 20 0d 0a 3c 69 6d 67 20 73 72 63 3d 22 68 74 74 70 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 3a 38 30 30 31 2f 6f 63 6d 61 2f 53 6e 69 70 70 65 74 43 6f 6e 74 65 6e 74 3f 73 65 67 49 64 3d 32 26 63 49 64 3d 31 32 36 26 72 49 64 3d 37 36 39 33 33 37 36 38 32 33 33 32 38 32 35 30 38 37 39 22 2f 3e 0d 0a 20 3c 2f 61 3e 20 20 20 20 20

Just as with other connection configuration types, the OMA Server connection configuration must be associated with an ad space owner provisioned in the Marketing and Advertising system.

Creating an OMA Ad Server Connection Configuration

The Marketing and Advertising network provider user must create an OMA Server connection configuration. To create an OMA Server connection configuration:

  1. As a network provider user click the Connection Configurations menu item

  2. Click the Create Connection Configuration button

  3. Click the OMA Server Connection Configuration button

  4. Enter a name in the Name field

  5. Enter an application ID in the OMA SP Application Identifier field

  6. Leave a value of 1 in the Maximum return ads number in one request field

    Note:

    Only a value of 1 is supported in this release of Marketing and Advertising. This value corresponds to a single ad or URI return for each external application ad request.

  7. Select the Channel Type to be used for the external application

  8. Assign an ad space owner using the search functionality

  9. Enter a value in the Max Ad Message Size field if needed

  10. Select if Delivery Notification should be enabled

  11. Click the search button to enable enhanced features if needed

  12. Click Save

Create an Ad Space Using the OMA Server Connection Configuration

A Marketing and Advertising Ad Space must be associated with the newly created OMA Ad Server connection configuration. To create an Ad Space for use with an external application:

  1. As an Ad Space Owner user click the Campaign Spaces & Campaigns menu item

  2. Click the Create New Campaign Space button

  3. Click the Create Ad Space button

  4. Enter a name in the Name field

  5. Enter a description in the description field

  6. Click the Search button for the Connection field

  7. Select the OMA Server Connection Configuration menu item to search for available OMA Server Connection Configurations

  8. Select the desired Connection Configuration

  9. Click OK

  10. Select if Dynamic Matching Category options if needed

  11. Click the Calendar button for each of the following fields and enter the required Bid and Campaign start and end times:

    • Bid Start Time

    • Bid End Time

    • Campaign Start Time

    • Campaign End Time

  12. Select the checkbox labeled Yes if the Ad Space is Fixed Price

  13. Enter a currency value for the Minimum Bid Price

  14. Click the Browse button to select an icon for the Ad Space if needed

  15. Click Save

The Ad Space created will become active and available for Advertiser bidding or fixed price purchase at the specified time. At the conclusion of the auction the campaign will start at the specified Campaign Start Time.

Bidding and Purchasing OMA Ad Space

Once the bidding period of an OMA Ad Server campaign is in effect advertiser users in Marketing and Advertising can bid or purchase Ad Space in the Marketplace. Ad Spaces eligible for bidding are presented in the advertiser web interface.

To use an OMA Server Ad Space, an advertiser must create Ad Content for the Channel Types that OMA Server Connection Configurations support. For information on creating Ad Content see in the Advertiser User's Online Help.

To enter a new bid on an OMA Ad Server Ad Space:

  1. As an Advertiser user click the Marketplace menu item to display Ad Spaces open for bidding

  2. Select the Ad Space to bid on

  3. Click the Enter New Bid button

  4. Enter a name in the Name field

  5. Enter a currency value in the Campaign bid price field

  6. Enter a value for the Maximum Number of Messages field to calculate the Total Price of the bid

  7. Select the desired ad content for use with the campaign

    Note:

    The Marketing and Advertising OMA Ad Server implementation supports text, URL and simple html snippet ad content as specified in the connection configuration.

    Ad Content is created and managed in the Advertiser user's Ad Portfolio found in the menu. Marketing and Advertising will only display ad content valid for the connection configuration being used.

  8. Click Save

A winning bid by an advertiser results in the bid's ad content being made available to an external application during the duration of the campaign.

Responding to External Application Requests Ad

When an external application/entity calls the SPAppAdRequest operation providing an SpAppID, Marketing and Advertising identifies and authenticates that the request is coming from the ad space owner. Marketing and Advertising will retrieve the winning advertiser's ad content and serve it to the external application/entity in a SPAppAdResponse message.

Reporting Ad Server Statistics

The external application/entity can provide statistical information on ads served (impressions) to Marketing and Advertising by utilizing the SPAppMetricsReport operation. See "SpApp Ad Web Service" for additional information.

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us