From I3d

Collaboration Suite

Silver Stream Products

Developer Tools

---

Silver Stream Advertisement API

Forum at: http://i3dnow.com/forum/

Company SL Location:

SL group: i3D Developer Associates

At a minimum, you will need the following API scripts

SilverStream Terminal Com	may also be named as 'yourOrganization Terminal Com'
SilverStream ad API	may also be names as 'yourOrganization ad API'

For extra API functionality you may also have the following

Silver Stream HTTP Handler	used to determine if in a SilverStream enabled region
detection	area data parsing package
prepare data	area data parsing package
ad implementation	Simple implementation of the API
agent sensor	Open agent sensor script

This API supports delivery of ads in the following modes (set in the Settings notecard)

VIDEO	A video advertisement delivered via the SilverStream Network.
IMAGE	An image delivered via the SilverStream Network.
TEXTURE	A texture ad.
TEXT	Chat based advertisement.

Use of this API requires that when extra data is available for an ad, that data is made available to agents viewing the ad.

General Process overview

The general process to request and recieve an ad is a follows:

1. Set appropriate settings in the notecard based on ad type.
2. Reset the system so settings are read.
3. Send ad context data via a link message on channel -114875244.
4. An ad returns based on the specified ad type (texture, streamed image, streamed video).
5. Set or hide weblink, notecard, and location buttons based on available ad information.
6. Return to step 3 after waiting for some interval.

Quick Implementation

Distributed with the package are several scripts that demonstrate a simple implementation of the ad API. By dropping in these scripts, an ad will be shown when an agent walks within sensor range of the object. Here is a description of the process.

Initialization

The api implementation script is reseet, which sends a reset message to the other scripts in the device to ensure all scripts are cleared and ready to run. This also signals to the ad API script to parse the Settings notecard to determine the ad method the following process will use. Some settings are delivered via link message to the agent sensor and Terminal Com.

Agent Detection

The agent sensor script detects when an agent is within range and maintains a list of agents who have been detected. When new agents are detected, they are sent to the Terminal Com and the current media is played for those new agents. Then, the current agent list is sent to Terminal Com so that agents who have left are removed from the system. If no agents are detected, all lists are cleared. This is only needed when using the IMAGE or VIDEO ad modes.

Requesting an ad

The detection and prepare data scripts work together as a simple method to request an ad. When a link message is sent on channel -114875244 with the text "PARSEAREA", these scripts will gather data from the objects it detects in the surrounding area. The api implementation script sends this message to trigger these scripts once every minute (by default) so that agents who remain within sensor range will be updated with a new ad.

The detection and prepare data scripts gather data and combine it into a %20 (URL encoded space) separated list of context info. This data is then prepended with WEBDATA:: and sent via a link message to the ad API. If different contectual data would work better, you can replace these scripts with your own method to provide the context data. Just prepend it with WEBDATA:: and make sure that the data is a %20 separated list of data.

An ad is returned

If the ad mode is IMAGE or VIDEO, then agents currently in the Terminal com portion of the API are automatically updated with the new medai. If the agent sensor script detects a new agent, that same media will be played. If the ad mode is TEXT, the advertisement will be said in open chat. If the ad mode is TEXTURE, a link message will be sent on channel -84916253 with a message that looks like:

textureAd::(key)

—

where (key) is the texture key of the ad to be displayed.

Also, the texture size information will be sent on that same channel so that resizing of a display can be implemented

adSize::(width)x(height)

—

where width and height are the size in pixels.

Enabling ad interface

Scripts have also been provided for a simple implementation of interactive buttons that allow an agent to request extra information (if available) on a showing ad. This functionality is required to be implemented in some way as part of the interface, though the method can be changed.

When an ad is returned, a link message will also go out on -84916253 in the following format:

adActions::WEBLINK::ENABLE::NOTECARD::DISABLE::TELEPORT::i3D::<128.0,128.0,128.0>

or

adActions::WEBLINK::ENABLE::NOTECARD::DISABLE::LOCATION::ENABLE

This message indicates whether that particular ad has that piece of extra data to go with it. The included scripts will set the buttons to 100% alpha when that functionality is disabled.

Weblink	when this button is touched, the user is taken to a webpage (external browser)
Notecard	This indicates there is something to be delivered. Could actually be objects instead. Notecard name was left instead of refactoring code at this time.
Location	Sent when a landmark is to be given instead of a direct teleport.
Teleport	This is sent instead of Location if a teleport is given (vice a landmark) The following items are Region and location information for llMapDestination which is required to be within the touch event of the button.

When a button is touched for one of these ad actions, a link message must be sent to the API as follows:

— must be sent on channel -84916253

— must have following message format "ACTION::(button)" where button is WEBLINK,NOTECARD, or LOCATION (used for both landmark and teleport actions)

— the (key) id part of the link message must contain the agent key that requested the information

When using this API, you must implement this functionality so that if this information is available, the agent can request it.

Repeat

At this point, one complete cycle is done. Another ad can be served up by sending context data again. This can be done with the same context data to bring up a different ad, or the same ad can be shown until the context data changes. The sample api implementation script, sends the request for context data to be sent once per minute.

Included scripts description

SilverStream Terminal Com (or yourOrganization Terminal Com)

This script contains all the API for playing media through the SilverStream Network See SilverStream API for more documentation on using this. Used by the ad API when the ad mode is set to IMAGE or VIDEO. Agents that should be viewing the media should be set using link messages on channel -255255 of either:

SETAGENTS::(csvAgentList) - where csvAgentList is the comma separated list of agents to play media for when new media is played

or

ADDAGENTS::(csvAgentList) - where csvAgentList is a comma separated list of agents to immeiately set to the current media the API holds (from a SETURL:: message)

ad API (or yourOrganization ad API)

This script contains the interface to request ads through our system. When reset, it reads the Settings notecard to determine the ad mode, and sends some link messages for other interested scripts.

The notecard lines the ad API looks for are

ad mode:[(mode)]	where (mode) is replaced by the ad mode (e.g. ad mode:[IMAGE])
display texture:[(key)]	where (key) is replaced by the texture key to use for media (e.g. display texture:[1597c3f3-8458-bf97-a65f-082eb3f38233] )when this is read a link message is sent with "SETTEXTURE::(key)"
sensor rate:[(rate)]	where (rate) is replaced by the agent sensor repeat rate this value is sent out as a link message by the API and is used by the agent sensor script. Sent as "SETSENSOR::(rate)"

When the API sees a link message on -114875244 that starts with "WEBDATA::", it will parse the information following the "::" as context information. It is expected that the context information is a "%20" separated list (URL encoded spaces). That data is then parsed and the ad API will return an ad based on the ad mode.

If it is IMAGE or VIDEO, the messages are automatically sent to play that media for agents that the Teriminal Com script is holding. If it is TEXT, the ad is said in open chat. If it is TEXTURE, a link message is sent as "textureAd::(key)" where (key) is the texture key of the ad

If the ad mode is TEXTURE, IMAGE, or VIDEO, another link message is sent with "adSize::(size)" with size containing the "(width)x(height)" of the ad in pixels so texture offsets and prim resizing for ratio preservation can be performed. If the ad mode is VIDEO, another link message is also sent with "adLength::(min):(seconds)" where(min):(seconds) is the length of the video in minutes and seconds.

The api also sends messages when the video is loaded to indicate if extra information is available for the ad. As follows:

adActions::WEBLINK::ENABLE::NOTECARD::DISABLE::TELEPORT::i3D::<128.0,128.0,128.0>

or

adActions::WEBLINK::ENABLE::NOTECARD::DISABLE::LOCATION::ENABLE

Teleport is handled differently as the button interface must call llMapDestination on touch so it goes to the correct agent.

When this information is requested, the API expects a link message on -84916253 with the following format: "ACTION::(button)" where (button) is replaced by WEBLINK, NOTECARD, or LOCATION (location serves for both teleport and landmark requests.

agent sensor

This is an open script that you can modify. It tracks agents that come into sensor range and send the correct messages to Terminal Com when new agents enter the sensor. It also clears agents that leave the sensor and all agents if no-sensor event occurs.

api Implementation sample

This sample sets the texture on face 2 of an object based on the link message it sees from the API It also sends out a "PARSEAREA" message to the detection script to gather and send context data to the API

weblink

This hides a prim (set to 100% alpha on one face) when disabled, and shows it when enabled by API messages. It also sends the link message to the API when touched, indicating the user wants that info.

location

This hides a prim (set to 100% alpha on one face) when disabled, and shows it when enabled by API messages. It also sends the link message to the API when touched, indicating the user wants that info, unless it was sent information for a teleport in which case it calls llMapDestination.

notecard

This hides a prim (set to 100% alpha on one face) when disabled, and shows it when enabled by API messages. It also sends the link message to the API when touched, indicating the user wants that info.

SilverStream HTTP Handler

Used to determine if the device is in a SilverStream enabled region.

detection

detects objects in the area.

prepare data

formats the detected object data into %20 separated list and hands over to the API script.