Embedded Impression Code

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.