oasisi-e.php
contains the code used to embed OASIS calls directly into your site's
pages. To use this method, you must run OASIS on your Web server, and
you can only embed the ads in PHP pages.
On the page where you want to embed an ad, you would have this:
<?php require("/home/webdocs/oasis/oasisi-e.php"); get_creative(5, 468, 60, ''); ?>
You will note that in the get_creative()
function call,
we specifying four things:
OASIS uses these three pieces of information to determine which creative to display to the user. It will search the list of creatives of the appropriate height and width which assigned to the section, and pick one based on a number of rules.
Before looking for candidate creatives, OASIS acquires a semaphore. Independent copies of the delivery engine must be able to scan the available creatives, select one, and update the "Remaining" field without trampling one another.
get_creative()
uses the exact same algorithm for selecting a
creative as is used in oasisi.php
. The only difference is
that get_creative()
also considers creatives with MediaType
of "RichMedia" (oasisi.php
only considers those with MediaType
of "Image").
Another difference between get_creative()
and
oasisi.php
is that get_creative()
does not
use the Delivery table to record which creative was seen by each user.
In the case of Image ads, the creative number is embedded right into
the URL that get_creative.php
generates for
oasisc.php
.
The following routines are shared between oasisi.php
and oasisi-e.php
:
get_client_id()
,
select_creative()
(with a minor change: it saves the MediaType
of the selected creative to a global variable for later use),
record_delivery()
, and
log_msg()
.
If for some reason, there is nothing of w x h assigned to section s (or if all have impression targets that have been met), the engine will not be able to select a creative to run. In such cases, it will deliver an empty string.
At this point, we have a creative ID. If the selected creative has a
MediaType of "Image", get_creative()
will return the HTML to display that
specific creative on the page (via a URL to oasisi.php
),
along with a cache-busting random number. If your call to
get_creative()
specified a frame target, the <A> tag will
include a "TARGET=" modifier.
If the creative has a MediaType of "RichMedia", get_creative()
will return the actual content of the ad (which presumably is of an
appropriate format to embed directly in the page). The frame target does
not affect RichMedia creatives.
OASIS records the delivery in oasis.log
(in the directory 'LogDir',
specified in the Preferences interface). Note that locally-served Image
ads are not recorded, since the subsequent request to oasisi.php
will record the impression. It records 'imp' for a successful
impression and 'ierr' when it has to deliver the 1x1 GIF. There are also
a number of codes we can record:
Event | Code | Description |
imp | successfully served impression | |
ierr | no_sem | couldn't acquire the semaphore |
no_sec_cr | no active creatives for the specified section | |
no_secdim_cr | no active creatives of the right dimension for the specified section | |
no_ht_shm | unable to connect to the HourlyTargets shared memory segment (diagnostics may be available in parentheses) | |
secdim_cr_maxed_out | the creatives assigned to this section are maxed out (all have targets, and all have remaining = 0) | |
no_ht_shm_2 | unable to connect to the HourlyTargets shared memory segment the second time, when we attempt to decrement the "remaining" count (diagnostics may be available in parentheses) | |
no_target_info | unable to retrieve target info from the HourlyTargets shared memory segment for the selected creative (diagnostics may be available in parentheses) | |
no_target_info_put | unable to put target info into the HourlyTargets shared memory segment for the selected creative (diagnostics may be available in parentheses) |
Note that each embedded ad makes two calls to the OASIS delivery engine,
the first when your PHP calls get_creative()
and the second when your
browser requests oasisi.php
. You don't have to worry about
these requests getting logged twice, though, because when
oasisi.php
is called with a specific creative number, it
does not log the request, knowing that get_creative()
already did the logging.
The log files are picked up hourly by
hourly_maint.php
, which distills
it down into a number of entries in the HourlyStats table.