ACP 1.0

This document is a technical description of the Additional Content Protocol. It describes the communication that will take place between the client and the various servers. The description follows the flow of information, from when a user first starts the client until the client sends reports on the content that has been shown. The ACP 1.0 protocol is written using XML.

Server

The servers are:

• DNS server
• registration server
• instruction server
• report server
• content server

When sending ACP requests and data between the client and the server, HTTP protocol should be used and the Content-Type should be "application/vnd.xacp".

Terminology

AP

Client Vendor, e.g. Opera

STP

Service Transaction Provider, e.g. Advertising.com

ACP

Additional Content Protocol

ACPO

Additional Content Protocol Object

Registration

When a user first starts the application, the application will send a registration request to the registration server. The registration server is initially hardcoded in the browser e.g. "rgs1.opera.com" with "rgs2.opera.com" as a backup server.

The following record is sent to the registration server using the "POST" method over HTTP:

<?xml version="1.0" encoding='ISO-8859-1'?>
<xacp version="1.0">
  <registration_request vendor="Opera" product="win32e4.03" distribution="SOL"/>
            <profile>
                  <property name="country" val="france"/>
                  <property name="gender" val="male"/>
            </profile>
</xacp>

The three variables (vendor, product, distribution) must be found in the distribution somewhere.

The <profile> element contains fields and values that Opera wants to report about the user. (These values are optionally specified by the user in program Preferences.) The ACP specification does not require any specific fields; it's a commercial and political issue.

In return, the browser will receive a structure like the following:

<?xml version="1.0" encoding='ISO-8859-1'?>
<xacp version="1.0">
  <registration_data status = "ok" user_code="123456">
  <instruction_server main="www.ins1.net" backup="www.ins2.net"/>
  <report_server main="www.rps1.net" backup ="www.rps2.net"/>
  <registration_server main="www.rgs1.net" backup="www.rgs2.net"/>
  <instructions>
  <remove_acpo code="1111"/>
  <next_connection units="exposures" count="12"/>
  <set_cache units="exposures" count="50"/>
  </instructions>
  </registration_data>
</xacp>

The browser must remember the user_code. This is a unique ID which will be used in all subsequent communication.

The returned server names are advisory. Some clients may have hardcoded names that are used instead or in addition to the returned names.

The instructions to remove certain ACPOs (see below) should be honored.

The instruction for making the next connection is in exposures or days, and the count is the number of exposures or days from the last connection.

If <registration_data> status is not "ok", and additional element may provide error codes and description, see example [1] below.

The instruction <set_cache> contains the basic unit that the client should use to calculate the buffer size, and the number of exposures or minutes of content that the client should hold in his local cache.

Requesting content

The registration process described above is only performed when Opera is started for the first time. Subsequently, Opera will ask for content when it is started. Here is the structure it should send to the instruction server:

<?xml version="1.0" encoding='ISO-8859-1'?>
<xacp version="1.0">
  <content_request vendor="Opera" product="win32e4.03" distribution="SOL" 
       user_code="123456"/>
  <client_connection last="2000-12-22" units="exposures" count="12"/>
    <needs>
      <content location="top" exposures="4"/>
      <content location="top" exposures="4"/>
      <content location="top" exposures="4"/>
      <content location="top" exposures="4"/>
    </needs>
    <avoid>
      <acpo code="2222"/>
      <acpo code="2223"/>
      <acpo code="2223"/>
      <acpo code="2422"/>
    </avoid>
    <profile>
      <property name="country" val="france"/>
      <property name="gender" val="male"/>
    </profile>
  </content_request>
</xacp>

The <client_connection> contains date of the last connection, and the basic unit that the client uses to set the next time it should connect to the server (either exposures or minutes). The count is the number of exposures/minutes of that the client should count efore trying to connect the server.

The <needs> element requests content for a certain "location". (Opera will have only one location (at least initially), on top.)

The <avoid> element list ACPO codes that:

• have "once" or "wait" policy set (see below); and
• the required number of days haven't passed (see below)

The <profile> element is used as described above.

Getting content metadata

In response to the content request comes a structure like the one below. It consists of a list of <acpo>; elements which contain metadata about the content which is to be displayed.

<?xml version="1.0" encoding='ISO-8859-1'?>
<xacp version="1.0">
 <content_data status = "ok">
   <instructions>
       <next_connection units="exposures" count="12"/>
       <set_cache units="exposures" count="50"/>
   </instructions>
   <acpo service="ad_redirect_random" code="1" location="top">
     <content display="when_online"
          href="http://servedby.advertising.com/click/site=126885/bnum=@@@@">
       <src url="http://servedby.advertising.com/site=126885/size=468080/
           bnum=@@@@/bins=1/rich=0"/>
       <resend policy="nolimit"/>
       <expiration exposures="30" clicks=30/>
     </content>
     <activities>
       <exposure report="enable"/>
       <click report="enable"/>
     </activities>
     <refresh exposures="1" clicks="1"/>
   </acpo>
 </content_data>
</xacp>

If <content_data> status is not "ok", an additional element may provide error codes and descriptions, see example [1] below.

The element <instruction_server> sets the default values for the instruction servers. The client uses this server to ask for the <content_request> record.

The element <report_server> sets the default values for the reports servers. The client uses this server to ask for the <activity_report> record.

>instructions< contain general instructions for the client to perform. In the case where no instructions are needed, this part won't be sent to the client side.

The instructions <next_connection> and <set_cache> behave as noted above in the registration process.

Server sends the <acpo service> instructions to tell Opera where to fetch banners.

Currently the only content types that Opera accepts are image types, such as gif, jpeg, and png.

The value of the "code" attribute is the unique ID of the ACPO. The priority goes from "0" to "4" - ACPOs with a higher priority should be shown first.

The "href" attribute of the <content> element contains the URL which should be loaded when the user clicks on the ad. The "display" attribute specifies when the ad can be shown: "when_online", "when_offline", "when_ever" (which is the default value. The <content> element can have three child elements: src, resend and expiration.

The <src> element simply lists the URL to the banner ad (which, in principle, can be any URL).

The <resend> element specifies when the ad can be resent to the client. It's important that Opera remembers these values - they are to be used when the <content_request> is sent.

The <expiration> element specifies when an ACPO should no longer be displayed. There's an implicit "or" between the attributes. E.g., this element:

<expiration latest="2000-04-13T17:55+01:00" 
exposures="6" clicks="1" accumulate="34:23"/>

can be read as "the ACP expires after six exposure" OR "one click" OR "after the accumulated time has reached 34:23" or the "latest" time has been reached.

The <activities> element describes in some detail what consitutes an "exposure" and whether exposures and clicks should be reported or not.

The <exposure> element has these attributes:

• "length" specifies the number of seconds the content must be visible in order to define one exposure.
• "accumulated_activity_period" specifies the minimum accumulated activity (in seconds) that must be detected in order to define it as an exposure. (Default value is "4" seconds).
• "window_size" -- both the name and function of this must be discussed. The activity window frame defined by user activity. The default value is "2" sec
• "report" takes two values: "enable" and "disable" whether the client should report on the activities counted from this type.

The <click> element only takes the "report" attribute. The default value is "enable".

Empty content_data

If the client receives an empty <content_data> element, this signals that the STP is no longer functional. The client should then submit another <registration_request> to the registration server to get a new user_code and information about new server.

At this point, all reports relating to the old STP and its ACPOs are sent off to the old registration server and the ACPOs are thereafter discarded.

Reporting activities

In order to gain revenue, Opera needs to report back on what ACPOs have been shown when and for whom. Also, clicks must be reported. Here is a sample:

<?xml version="1.0" encoding='ISO-8859-1'?>
<xacp version="1.0">
  <activity_report vendor="Opera" product="win32e4.03" 
      distribution="SOL" user_code="123456"/>
  <client_connection last="2000-12-22" units="exposures" count="12"/>
    <acpo code="2222">
      <exposure location="top" date="2000-12-22" count="5"/>
      <exposure location="top" date="2000-12-22" count="5"/>
      <exposure location="top" date="2000-12-22" count="1"/>
      <click location="top" date="2000-12-22" exposures="2"/>
    </acpo>
    <acpo code="1111">
      <exposure location="top" date="2000-12-22" count="5"/>
      <exposure location="top" date="2000-12-22" count="5"/>
      <exposure location="top" date="2000-12-22" count="1"/>
      <click location="0" date="2000-12-22" exposures="2"/>
    </acpo>
  </activity_report>
</xacp>

The instruction <client_connection> behaves in the same way as described above in the "Requesting content" section.

The <exposure> element reports exposures for a given ACPO. Several exposures can be accumulated through the "count" attribute. The default value of "count" is "1".

The <click> element reports a single click. The "exposures" attribute gives the number of exposure events that took place before the click event.

Activity acknowledgment

The <activity_ack> is the response to an <activity_report>.

<?xml version="1.0" encoding='ISO-8859-1'?>
<xacp version="1.0.0">
    <activity_ack status = "ok">
    <status_information>
        <message code="2010" content="GENERAL Error: Wrong vendor">
        <message code="2011" content= 
             "GENERAL Error: Wrong distribution code">
    </status_information>
    <next_connection units="exposures" count="12"/>
</acp_interface>
</xacp>

The "status" attribute tells the client whether the report was correctly processed or not.

If the status is "fatal error", the report was not accepted. The <status_information> element provides the error codes and messages. See below.

The <next_connection> element tells the client when to do the next report (number of exposures or number of days).

Notes

[1] The following is an example of the element that shows possible error codes and descriptions:

  
   <status_information>    
   <message code="2010" content="GENERAL Error: Wrong vendor">
   <message code="2011" content="GENERAL Error: Wrong distribution code">
   </status_information>

This element will not be present if there are no errors.

Copyright Opera Software ASA. All rights reserved. | Support | Contact | Privacy