oasisi.php
is the script used to deliver an impression.
oasisi.php
is responsible for delivering image banner
impressions
when you are using the IMG tagging delivery method. In this case, the URLs take
the form
<IMG SRC="http://oasis.yourdomain.com/oasisi.php?s=5&w=468&h=60"
BORDER=0 HEIGHT=468 WIDTH=60>
You will note that in the tag, we specifying three 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.
OASIS will first poll the Hourly Assignments shared memory segment for the list of all w x h creatives (of MediaType "Image") assigned to section s. It will then go through each of these and pull from the Hourly Targets shared memory segment the hourly impression target, weight, and number of remaining impressions needed to meet the hourly target.
Creatives with non-zero impression targets and zero remaining are ignored. These have already reached their hourly targets and should not run any more this hour.
If there are any creatives with non-zero impression targets where the number remaining is greater than 0, these get top priority. They are weighted according to the number of remaining impressions, and then one is randomly selected.
If there are no creatives with non-zero impression targets and more than zero remaining impressions, one of the creatives with a zero impression target is selected, according to the weights assigned to these creatives.
When OASIS randomly selects a creative, it basically adds up the weights of all candidate creatives (or in the case of non-zero-impression-target creatives, it uses the remaining impressions as "weights"); then selects a random number from 0 to the sum of the weights. It then loops through the candidates, decrementing the random number by each candidate's weight until the random number is less than zero. Whichever candidate causes the number to be less than zero is the creative served.
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 (and in any
cases where the delivery engine encounters an error with shared memory
or a semaphore), it will deliver
a 1x1 invisible GIF (the actual GIF data is hard-coded into
oasisi.php
).
At this point, we have a creative ID. OASIS will now decrement the Remaining field for the creative (it is unfortunate that we can't do this later, after we've actually delivered the content to the user, but if we waited that long, we'd be holding the semaphore for too long, which would have a huge impact on performance). OASIS immediately records the delivery in oasis.log (in the directory 'LogDir', specified in the Preferences interface). It records 'imp' for a successful impression and 'ierr' when it has to deliver the 1x1 GIF. The shared memory and log are updated within the protection of the semaphore, and are done one after the other to reduce opportunities for an impression to get recorded in one but not the other. OASIS will now retrieve the actual content of the creative from the Creative Content shared memory segment. Here is pseudocode for the retrieval process:
if(creative is a third-party creative) { #### content is a text string representing the URL for the #### third-party ad server replace "[CB]" strings in the URL with random number save the Location header (along with some cache control headers) } else { #### content is binary data for a GIF image #### we can only print cache control headers for non-animated #### GIFs (doing so with animated GIFs results in browsers looping #### through a series of GIFs -- it's really wacky) if(creative is not animated) { save some cache control headers } save MIME type header save content }
The Delivery table is now updated to record which creative was seen by the user on section s, so that if the user clicks through, he will be directed to the proper clickthrough URL. The delivery is recorded twice; once using the OASISID cookie number (either presented by the client or just now assigned to him) and once using the IP address. Although we hope that the user is accepting cookies, and we will be able to use the cookie to deliver the right clickthrough, we can't make that assumption, so we also have to record the IP address as a sort of backup. If we have to rely on the IP address, the clickthrough accuracy cannot be guaranteed, but it's better than nothing.
Finally, the headers and the content saved during the retrieval step are sent to the user, and the delivery engine is done.
Log Codes Here are the meanings of the various codes logged by the delivery engine.
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) |
These log files are picked up hourly by
hourly_maint.php
, which distills
it down into a number of entries in the HourlyStats table.
oasisi-e.php
is responsible for the
bulk of the work described in this section. But to actually
deliver an Image banner, it will call oasisi.php
.
The link generated by oasisi-e.php
will take the
form
<IMG SRC="http://oasis.yourdomain.com/oasisi.php?c=45"
BORDER=0 HEIGHT=468 WIDTH=60>
This form specifies exactly which creative is to be delivered.
oasisi.php
doesn't have to do much work in this case;
it simply has to deliver the contents of the designated creative.
It is not advisable to use links of this form directly in your
site's pages. If you're not using oasisi-e.php
to deliver the ads, specify the section, width, and height
to oasisi.php
and let OASIS make the decision of
which creative to run.