Skip to end of metadata
Go to start of metadata

We do not maintain the support for Windows SDK anymore. We will update the page if and when we are back with the support for Windows

1. Introduction

The SOMA SDK library for Windows (Phone) enables a software developer to easily integrate SOMA Ads in their Windows (Phone) applications.

The SDK connects with the SOMA server and downloads the ad in the background.

By default, a new ad is downloaded every 60 seconds.

The SDK can display the ad and support the click through to see the full page ad in a Browser Window.

The SOMA SDK for Windows & WP consists of two layers:
1. Presentation Layer, SomaAdViewer, which is the normal way to use the SDK.
2. Communication Layer, SomaAd, which gives the developer more control. The communications layer is used by the Presentation Layer to connect with the SOMA Ad Server and download the ads.


2. Sample Apps

The SDK includes four sample apps that demonstrate the three ways to use the SDK:

  1. SOMA Sample – Pres Layer Design Time – in this sample the SomaAdViewer Control is instantiated at design time and the required properties are also set at design time.
  2. SOMA Sample – Pres Layer Execution Time – in this sample the SomaAdViewer Control is instantiated at execution time as well as the required properties.
  3. SOMA Sample – Communications Layer – in this sample SomaAd is used; its properties and methods are set at execution time to retrieve ads which are then displayed by the developer.
  4. SOMA Sample – XNA = Comm Layer – in this sample SomaAd is used; its properties and methods are set at execution time to display ads in an XNA environment.

3. Overview of Presentation Layer – SomaAdViewer

The SomaAdViewer Control may be instantiated by the developer at either design time or at execution time. It will then invoke the Communication Layer to connect to the SOMA server and retrieve the ads on a background thread. When an ad has been received, the Presentation Layer will display the ad in a Web Browser Control. When the ad is tapped by the user, a Web Browser Task is launched in a new windows displaying the associated click- through ad. The developer should be sure to perform the normal state save and restore tasks to preserve their application’s user interface.


4. Overview of Communications Layer – SomaAd

The Communication Layer will handle the ad request, the parsing of the XML response, the download of the ads (and beacons) and the handling of errors. The application developer will not be able to bypass this layer. The interface of the Communications Layer will provide access to the following data:

  • Type of ad (text or image)
  • Ad (the text and/or the image byte stream)
  • Click-through-action URI

The Communications Layer runs as a background thread. Its ongoing activity will never block the application from working.
The Communications Layer will allow the setting of the properties identified below. The Communications Layer will require an Ad Request object as a parameter that has as its properties, the ad parameters. All requests done by the SDK will use the phone browser’s user agent. The same communications layer can be used whether the application is Silverlight or XNA based.


5. Using the SOMA Presentations Layer – SomaAdViewer – with design time instantiation

To get started using the SomaAdViewer you must add a reference to the SOMAWP.DLL in your project. It is distributed as part of the SDK. Next, while displaying the design canvas for the page where you want ads, right-click in the toolbox and select “Choose Items”. Now click the Browse Button in the lower right of the dialog box. Browse to the SOMAWP.DLL and select it. The Windows Phone Components list will now include SomaAdViewer. Select it by checking the box in front of it and press the OK button. Your Toolbox will now contain the SomaAdViewer Control. Drag it to your design surface. Set the left Margin control to 0.

In the properties window for the SomaAdViewer Control, you must set the pub property with your Publisher ID and the adSpace with your AD Space ID. Pub and adSpace of 0 can be used for testing.
You can optionally set the following demographic properties to enhance the ads retrieved:

PropertyDescriptionPurposeTypeExample
AgeAge of the userTargeting demographicInt30
GenderGender of the userTargeting demographicCharacterm or f
KwsKeywords describing the content of the pageTargeting ParameterComma separated valuesAutomotive news, cars
QsSearch StringTargeting ParameterComma separated valuesMadonna ringtone, fast, food, football

The following properties can be used to set the location of the user. By default, the SDK sets it to the current location:

PropertyDescriptionPurposeExample
CityLocation of user – cityTargeting Parameterredwood+city
StateLocation of user – stateTargeting Parametercalifornia
CountryLocation of user – countryTargeting Parameterunited+states
CountrycodeLocation of user – ISO-3166-1Targeting Parameterus
ZipLocation of user – postal codeTargeting Parameter94539
?GPSCoordinates of the users location, set by the SDK but can be overridden by the developerTargeting Parameter37.530676%2C- 122.262447
  • You can use the following properties to control the ads:
  • AdSpaceHeight – height of ad space
  • AdSpaceWidth – width of ad space
  • AdInterval – the number of milliseconds between ads; default is 60000 or 60 seconds;
  • LocationUseOk – when true, Windows Phone Location Services will be used to determine the current location when requesting Ads from SOMA.
  • BackgroundColor – can be used to specify a string that identifies the background color of the SomaAdViewer control when displaying the ad; by default the WP Theme color will be used; this is the tml hex string like #FFFFFFFF.
  • ShowErrors – when true, errors from SOMA Ad Server will be shown in the ad display area;
  • Debug – When true, an email will be generated whenever the SDK encounters an error exception;
  • Format – control which format ads are requested
  1. All: image, text or rich media ads;
  2. Img: image ads only;
  3. Txt: text ads only;
  4. Richmedia: Rich Media ads only
  • ModifyRM – if true Rich Media ads may contain MRAID compliant ads. PopupAd – When true, the height of the ad will be set to 0 at instantiation; when an ad arrives, the height will be animated to 100 over 1⁄2 second, then the ad will remain visible for the duration specified in PopupAdDuration, then the height will be animated to 0;
  • PopupAdDuration – The number of milliseconds an ad will be shown if PopupAd is true; this defaults to 10000 (10 seconds) which is its minimum.
  • Status – This is set to “started” after StartAds is processed and “stopped” after StopAds is processed, this is especially useful in the XNA environment as shown in the Sample for XNA.
You can use the following methods to control ad retrieval:
  • StartAds – if ads are stopped, will start retrieving them;
  • StopAds – if ads are being retrieved, it will stop the retrieval, StartAds must be used to restart the retrieval of Ads.
  • Dispose – Disposes of the SomaAdViewer control.
There are three events available:
  • “NewAdAvailable” is notified whenever a new ad is ready for display. 
  • “AdError” is notified whenever an error is encountered retrieving an Ad; SomaAd.ErrorCodes is an Enum for the Error Codes 
  • “AdClick” is notified whenever an Ad is Clicked by the user. 

6. Using the SOMA Communications Layer for WP – SomaAd

In order to use the SOMA Communications Layer for Windows Phone, first add a reference for SOMAWP.DLL to your Windows Phone project. Then add a Using to the module in which you want to get ads.
Next instantiate the SomaAd class like this:

somaAd = new SomaAd();

Then add your PubID and AdSpaceID like this:

somaAd.Adspace = 12345678;
somaAd.Pub = 12345678;

By default, a new ad will be delivered 60 after the previous one. You can change that. This shows changing it to 90 seconds:

somaAd.adInterval = 90000;

Next, set whatever demographics you want which can be changed on the fly for each ad:

// demographics
somaAd.Age = 30;
somaAd.Gender = “m”;
somaAd.City = “Fremont”;
somaAd.State = “Ca”;
somaAd.Zip = “94539″;
somaAd.Country = “United States”;
somaAd.Countrycode = “us”;

Now you need to add an Event to receive notification when a new ad is available:

somaAd.NewAdAvailable += new
SomaAd.OnNewAdAvailable(somaAd_NewAdAvailable);

When you want to start receiving SOMA ads invoke the GetAd method:

somaAd.GetAd();

You need a Delegate to receive the ad available notification. In this Event Handler you first check to see if there was an error. If not, you need to see if the ad is an image or text and handle accordingly. This code shows the SOMA Ad image in both a Image Control and a WebBrowser Control so that you can choose which to use.

void somaAd_NewAdAvailable(object sender, EventArgs e)
{
if (somaAd.Status == “error”)
{
textBoxErrorCode.Text = somaAd.ErrorCode;
textBoxErrorDescription.Text = DateTime.Now.ToShortTimeString() + ” ” +
}
else
{
if (somaAd.AdText != String.Empty)
textBoxTextAd.Text = somaAd.adText;
if (somaAd.AdType == “IMG”)
{
++adCounter;
textBoxAdCounter.Text = adCounter.ToString();
textBoxGifCounter.Text = somaAd.GifImageCount.ToString();
textBoxImageType.Text = somaAd.ContentType;
int pixelHeight = somaAd.AdImage.PixelHeight;
int pixelWidth = somaAd.AdImage.PixelWidth;
webBrowserAdImage.Source = new Uri(somaAd.AdImageUri);
}
} }

Next, you need to handle a user tap on the ad. This shows using the Mouse Enter Event on the Image control to display the target landing site associated with the Ad. This code uses the WebBrowser Control to display the target. However, you could also use the WebBrowserTask to do this. In the XAML, there is a Grid control for the WebBrowser called wbGrid. The sample code included shows how to do this.

WebBrowser wb;
private void imageAd_MouseEnter(object sender, MouseEventArgs e) {
if (somaAd.uri != “” && somaAd.uri != string.Empty)
{
wb.Source = new Uri(somaAd.uri);
ContentGrid.Visibility = Visibility.Collapsed;
wbGrid.Visibility = Visibility.Visible;
} }

In order to shut down the ads, use the Dispose() method. This BackKeyPress Event Handler illustrates doing this as well as handling the WebBrowser control:

private void PhoneApplicationPage_BackKeyPress(object sender,
System.ComponentModel.CancelEventArgs e)
{
if (wbGrid.Visibility == Visibility.Visible)
{
e.Cancel = true;
wbGrid.Visibility = Visibility.Collapsed;
ContentGrid.Visibility = Visibility.Visible;
}
else
{
MessageBox.Show(“Application Closing”);
somaAd.Dispose();
}
}
MethodsTypeSummary
SomaAdVoidConstructor for instantiating a SomaAd object
GetAdVoidStart the Get Ads from SOMA server process
DisposeVoidDispose of the SomaAd object
EventTypeSummary
GetAdErrorOnGetAdErrorNotified when an error is encountered while retrieving an ad from the SOMA Server
NewAdAvailableOnNewAdAvailableNotified when a new ad is available from the SOMA Server

AdImageFileNamestringname of file containg the ad image if adType is image

  • set by SDK; read only for developerAdImageUristringimage URI
  • set by SDK; read only for developerAdIntervalintinterval in milliseconds between ads; minimum 60000AdspaceintAD Space ID assigned by Smaato – ID “0″ can be used for unattended testingAdSpaceHeightintHeight of ad space
  • On Mobile the screen height can be usedAdSpaceWidthintWidth of ad space
  • On Mobile the screen height can be usedAdTextstringad text if adType is text
  • set by SDK; read only for developerAdTypestringad type – image or text
  • set by SDK; read only for developerAgeintTargeting parameter – age of the userCitystringTargeting parameter – location of the user – set by SDK to current location
  • can be overriden by developer – Example: redwood+cityContentTypestringType of content returned from SOMA ServerCountrystringTargeting parameter – location of the user – set by SDK to current location
  • can be overriden by developer – Example: united+statesCountrycodestringTargeting parameter – location of the user – set by SDK to current location
  • can be overriden by developer
  • Format according to ISO-3166-1 (2 digit) – Example: usDebugboolDebug True causes email to be sent to Smaato if there is an errorErrorCodestringerror code – see ErrorCodes enumErrorDescriptionstringerror descriptionFormatFormatRequestedFormat – control which format ads are requested
    • All: image, text or rich media ads;
    • Img: image ads only;
    • Txt: text ads only;
    • Richmedia: Rich Media ads onlyGenderstringTargeting parameter – gender of the user – m or fGpsstringTargeting parameter – ps coordinates of the users location
  • set by SDK to current location using cell tower triangulation
  • can be overriden by developer
  • latitude and longitude in decimal degrees format – comma (%2C) separated
  • Example – 37.530676%2C-122.262447ImageOKboolImageOK is true when the image in AdImageFileName is ready to use; required for
    XNA SAMPLEKwsstringTargeting parameter – keywords describing the content (e.g. automotive news)
  • comma separated values
  • example: motorsport, news, carsLocationUseOKboolwhen true, current location will be used as a parameter for obtaining ads.ModifyRMBoolDetermines whether Rich Media ads can contain MRAID compliant adsPubintPublisher assigned by Smaato – ID “0″ can be used for unattended testingQsstringTargeting parameter – search string ((e.g. Madonna ringtone)
  • comma separated values
  • example: beyonce, ringtones, fast, food, footballStatestringTargeting parameter – location of the user state – set by SDK to current location
  • can be overriden by developerStatusstringstatus – error means get ad failed errorCode contains code for failure
    errorDescription contains description of reasonUristringclick thru action uri; available when ad is available – set by SDK; read only for developer?ZipstringTargeting parameter – postal code of the current location of the user – set by SDK to current location – can be overriden by developer

AdImageFileNamestringname of file containg the ad image if adType is image
- set by SDK; read only for developerAdImageUristringimage URI
- set by SDK; read only for developerAdIntervalintinterval in milliseconds between ads; minimum 60000AdspaceintAD Space ID assigned by Smaato – ID “0″ can be used for unattended testingAdSpaceHeightintHeight of ad space
- On Mobile the screen height can be usedAdSpaceWidthintWidth of ad space
- On Mobile the screen height can be usedAdTextstringad text if adType is text
- set by SDK; read only for developerAdTypestringad type – image or text
- set by SDK; read only for developerAgeintTargeting parameter – age of the userCitystringTargeting parameter – location of the user – set by SDK to current location
- can be overriden by developer – Example: redwood+cityContentTypestringType of content returned from SOMA ServerCountrystringTargeting parameter – location of the user – set by SDK to current location
- can be overriden by developer – Example: united+statesCountrycodestringTargeting parameter – location of the user – set by SDK to current location
- can be overriden by developer
- Format according to ISO-3166-1 (2 digit) – Example: usDebugboolDebug True causes email to be sent to Smaato if there is an errorErrorCodestringerror code – see ErrorCodes enumErrorDescriptionstringerror descriptionFormatFormatRequestedFormat – control which format ads are requested
- All: image, text or rich media ads;
- Img: image ads only;
- Txt: text ads only;
- Richmedia: Rich Media ads onlyGenderstringTargeting parameter – gender of the user – m or fGpsstringTargeting parameter – ps coordinates of the users location
- set by SDK to current location using cell tower triangulation
- can be overriden by developer
- latitude and longitude in decimal degrees format – comma (%2C) separated
- Example – 37.530676%2C-122.262447ImageOKboolImageOK is true when the image in AdImageFileName is ready to use; required for
XNA SAMPLEKwsstringTargeting parameter – keywords describing the content (e.g. automotive news)
- comma separated values
- example: motorsport, news, carsLocationUseOKboolwhen true, current location will be used as a parameter for obtaining ads.ModifyRMBoolDetermines whether Rich Media ads can contain MRAID compliant adsPubintPublisher assigned by Smaato – ID “0″ can be used for unattended testingQsstringTargeting parameter – search string ((e.g. Madonna ringtone)
- comma separated values
- example: beyonce, ringtones, fast, food, footballStatestringTargeting parameter – location of the user state – set by SDK to current location
- can be overriden by developerStatusstringstatus – error means get ad failed errorCode contains code for failure
errorDescription contains description of reasonUristringclick thru action uri; available when ad is available – set by SDK; read only for developer?ZipstringTargeting parameter – postal code of the current location of the user – set by SDK to current location – can be overriden by developer

PropertyTypeSummary
AdImageBitmapImageNO LONGER SUPPORTED – since a BitMapImage only supports JPEG and PNG
and most ads are GIF, this makes no sense to use
The AdImage is in Isolated Storage in the file AdImageFileName
ad image if adType is image
- set by SDK; read only for developer

  • No labels