Mocean SOAP API Documentation

From Mocean Mobile Wiki

Jump to: navigation, search

The Mocean SOAP API document is intended for gathering all the information related to Mocean SOAP API usage.

Contents

Overview

The Mocean service SOAP API provides the programmatic access to all solutions within the Mocean Mobile system. By using the secure Application Programming Interface (API), the user is able to connect to the Mocean Mobile Server in order to automate or perform various operations.

Mocean SOAP API functionality allows clients to create things within the platform without having to go into the actual UI of the platform. Almost anything that can be done via the portal UI can be supported via API’s. Clients are able to create their own systems and software to make use of API’s and submit commands for things to happen.

There are some security and validation to ensure the system sending commands has permission to create, edit or delete the entities being created/edited/deleted. This includes using Private API Keys and related Network ID’s, that is validated against user permissions within the specific network. Also, network owners can create SOAP IPs Whitelist for the network to accept commands coming only from the specified IPs. To get more information about SOAP IPs Whitelist, please refer to Edit Custom Preferences.

The Mocean service SOAP API uses XML-based technologies,

  • Simple Object Access Protocol (SOAP)
    Allows for exchanging the structured information providing the communication between the user and Mocean Mobile Server.
  • Web Services Description Language (WSDL)
    Provides the interface description language.

Audience

This document is intended for developers who want to leverage Mocean Mobile data for their goals, or integrate Mocean Mobile products in their own environment.

Mocean SOAP API Documentation assumes you are familiar with the following:

  • Development practices
  • Web Services
  • SOAP and XML
  • Mobile Advertising

API Key Access

  • API Key Generation
    API Key are auto-generated right away when the user is created. So all users will have keys, but they can only access them and see them if the Network Settings “API Access” permission is enabled.
  • API Key Access enabling/disabling
    “API Access” permission can be enabled/disabled at the network/user profile level.
  • API Key Getting
    • Users are able to get their API access keys (in case they have the related permission enabled) from the Advertiser/Publisher/Manager/Network Owner profile edit form.
    • API Key for network managers can be viewed at the admin network panel (Control Panel >> Edit Advanced Network Settings >> Manage Users form >> Select Existing Manager >> Edit/Regenerate API Key).
    • Network owners and managers are able to acquire API access keys for Advertisers (if they have ‘Edit Advertisers’ permission enabled) and Publishers (in Mocean for Networks product) through the user edit form.
  • API Key Regeneration
    To re-generate the API key click the “Regenerate API Key” button on the User profile form or select the “Regenerate API Key” option under the Action column in the table of network managers. When the button is clicked or the option is chosen, a small modal window asking the user, "Are you sure you want to regenerate the API Key?" with Yes and No buttons will appear. When Yes, the original key becomes inactive and a new one is created. When No, the window closes and nothing happens. This can be initiated by the user whose profile is being viewed.
  • User API Key Export
    A section to generate a Profile report to display all Accounts existing in the network including the Accounts API keys is available in the "Advanced Network Settings", below the User Management table.

SOAP API Methods

SOAP API Methods can be used with any solution that supports SOAP protocols (e.g. SoapUI).

Basic instructions on how to navigate and operate in SoapUI can be found at http://www.soapui.org.

Getting Started

To get Mocean SOAP API methods start a new project and enter the following information:

  • "Project Name" - Give your project a name to identify it among the others (e.g. Mocean SOAP project)
  • "Initial WSDL/WADL" - Specify an initial WSDL file to import the methods.
Mocean SOAP API methods for object management can be imported from http://[network_domain].moceanmobile.net/soap/v[version_number]/objects/wsdl.
Mocean SOAP API methods for reporting can be imported from http://[network_domain].moceanmobile.net/soap/reporting/wsdl.

NOTE: The initial URL version http://[network_domain].moceanmobile.net/soap/objects/wsdl will always correspond to the 1st one http://[network_domain].moceanmobile.net/soap/v1/objects/wsdl.

Then set desired settings and select OK. The project gets created as specified.

As it has been mentioned above the Mocean SOAP API methods are of two types depending on their aim:

  1. Object Management - to manage objects i.e. to create, edit, delete, copy, etc. as well as get object information.
    Please go to SOAP API Object Management Methods v1 to get the description for methods of the 1st (initial) API version.
    Use SOAP API Object Management Methods v2 for the 2nd API version and SOAP API Object Management Methods v3 for the 3rd one.
  2. Reporting - to get reporting on the objects' activity in the system.
    SOAP API reporting methods are described at SOAP API Reporting Methods v1 and SOAP API Reporting Methods v2, v3. Use one of them subject to the SOAP API version you use.

When start working with Mocean SOAP API methods and searching among them it can be extremely helpful to know how they are named. Actually the method's purpose is reflected in its name. The following logic is implemented to Mocean SOAP API methods naming:

For Object Management methods
SOAP object management methods name structure
For Reporting methods
SOAP reporting methods name structure

To select a necessary method you should decide what action to implement on which object.

For instance, to receive the information on what regions registered in the database for a specific country you should select the getRegionsByCountry method. If you would like to set keywords in your targeting group, select the setKeywordsTargeting method.
As for reporting methods, the getZoneExternalReportBySite method for example will return the zone external data grouped by sites.

What each type of Mocean SOAP API methods does:

  • get-methods - allow users to receive the list of object with accompanying information for them (IDs, values, etc.).
  • add-methods - add new objects and return its elements with all the existing objects in a line.
  • create-methods - create new objects; returns its elements.
  • edit-methods - change object elements.
  • copy-methods - copy the object with all its elements.
  • set-methods - replace old object with a new one.
  • delete/undelete-methods - delete/undelete an object.
  • start/pause-methods - start/pause an object (implemented to orders and line items).
  • approve/decline-methods - approve/decline an object (implemented to sites under the Mocean for Networks product only).


There are limits for the request processing:

  • The system allows for processing up to 3 requests simultaneously.
  • If there are more requests, they are kept in the queue for 10 seconds waiting for the resources. If the request hasn't been processed for 10 seconds, it will be dropped and the client will get an error message and will have to retry the request again.

Request Body Structure

Each WSDL-based service exposes a number of methods that each have a request and response message format. In soapUI, the operations are shown as nodes under the Main node in the project navigator.

The bottom left properties section shows a number of read-only values for inspection purposes.

Double-click the method name in the left-hand window opens the request editor consisting of 2 panels, one for the request (at the left) and one for the response (at the right).

The XML view can be used for both request and response.

The XML request scheme represents an editable form where necessary object element values should be typed in. Some of them are required, and some of them are optional (marked as <!--Optional--> above).

<rep:getZoneExternalReportByLineItem>
   <fromDate xsi:type="xsd:string">?</fromDate>
   <toDate xsi:type="xsd:string">?</toDate>
   <!--Optional:-->
   <networkIds xsi:type="rep:ArrayOfInt">
      <!--Zero or more repetitions:-->
      <item xsi:type="xsd:int">?</item>
   </networkIds>
   <!--Optional:-->
   <accountIds xsi:type="rep:ArrayOfInt">
      <!--Zero or more repetitions:-->
      <item xsi:type="xsd:int">?</item>
   </accountIds>
   <!--Optional:-->
   <siteIds xsi:type="rep:ArrayOfInt">
      <!--Zero or more repetitions:-->
      <item xsi:type="xsd:int">?</item>
   </siteIds>
   <!--Optional:-->
   <zoneIds xsi:type="rep:ArrayOfInt">
      <!--Zero or more repetitions:-->
      <item xsi:type="xsd:int">?</item>
   </zoneIds>
</rep:getZoneExternalReportByLineItem>

The object elements are grouped by the following rule:

  • Several items within one element are joined with OR-operation so the response will return the data for each of them.
  • The AND-operation is applied to object elements so the response will bring up data for all elements if they correspond to one another: zones belong to the specified sites which on their turn are assigned to the specified accounts in the specified networks. If the specified items of some elements contradict each other, the empty response will be returned.

The element values should be entered instead of "?" marks.
If a value isn't specified for an optional element, the item should be commented-out. Otherwise an empty response will be received.

<obj:getOrders>
   <!--Optional:-->
   <networkId xsi:type="xsd:int"></networkId>
   <!--Optional:-->
   <accountIds xsi:type="obj:ArrayOfInt">
      <!--Zero or more repetitions:-->
      <!--<item xsi:type="xsd:int"></item>-->
   </accountIds>
</obj:getOrders>

Main SOAP Use Cases Layouts

Network User Profiles

A user can be created in the system by a Mocean representative upon request. As soon as a user is created in the system he gains an account and a right to create a network as a Network Owner. Network Owner is a role granted to him with the range of permissions so that he could efficiently act within the network. There are 6 basic roles in the system:

  • Network Owner/Superuser
  • Manager
  • Advertiser
  • Self-Serve Advertiser
  • Publisher
  • Self-Serve Publisher

Each of them is characterized with the range of permissions granted. These are permissions that determine users' ability to perform any actions within the network or access to reporting data.

From the 6 base roles, any number of custom roles can be created with individual sets of permissions. They are stored in the system database and can be used in different networks at the moment.

As soon as the network is created a Network Owner can create/invite other users to his network and create profiles for them. A profile includes user's personal and contact information accompanied with a role granted to him.

In different networks one and the same user may act under equal roles but with a unique profile. For instance, a user may act as a Manager in different networks. But in each network he will have an individual profile.

Within one network only one permission profile can be assigned to one user. A picture below displays how user's roles and profiles may correlate within one network and in several networks within the system.

User

Below you may find the information on how user profiles can be managed through SOAP methods.

  • Create User Profile
Network Owner and Network Managers are able to create/edit Advertisers and Publishers for the network using the createUserProfile method. The method alongside with the personal data like Name, E-mail, Address, etc. requires the role identifier and the network identifier.
The information about roles that are available in the network can be accessed via getRoles.
If you know the role identifier and would like to get permissions granted to the specific role, you may use the getRole method.
The information about networks the user is able to create a user for can be obtained using the getNetworks method.
Network Owners are able to create Managers too.
  • Edit User Profile
To edit user profiles the editUserProfile method is to be used. For this, the user profile ID is required and can be obtained via the getUserProfiles method.
  • Delete User Profile
Network Owners and Managers also may delete the specific user profile using the deleteUserProfile method by passing profile ID that can be obtained using the getUserProfiles method.
  • Get User Profile Related Information
If you know the user account ID and would like to get the full information about the user profile, you may use the getUserProfile method.
The user account ID can be obtained through the getUserProfiles method. If the user account ID not specified, the system will return the information on all users profiles existing in network determined by the entered API key.
The list of User Profile custom fields (attributes) existing in the network can be obtained via getUserProfileAttributes method.
  • API Key
The getUserApikey method returns API key for the specific network user. NOTE: A network owner can get API keys for all network users. A manager can get API keys for all publishers (Mocean for Networks) and advertisers. Each user can get his own API key.
The network user can reset API key using the resetUserApiKey method. NOTE: A network owner can reset API keys for all network users. A manager can get API keys for all publishers (Mocean for Networks) and advertisers. Each user can reset his own API key.
  • Advertisers Blocking
This functionality is implemented in Mocean for Networks only!
Advertiser can be blocker by users with appropriate permissions using the addBannedAdvertisers method or the setBannedAdvertisers method (the latter resets all the previously made settings if any).
The getBannedAdvertisers method allows users to get the list of blocked advertisers for a specified account or a network.
Advertiser can be un-blocked using the deleteBannedAdvertisers method.
  • Publishers Blocking
This functionality is implemented in Mocean for Networks only!
Publishers can be blocker by users with appropriate permissions using the addBannedPublishers method or the setBannedPublishers method (the latter resets all the previously made settings if any).
The getBannedPublishers method allows users to get the list of blocked publishers for a specified account or a network.
Publisher can be un-blocked using the deleteBannedPublishers method.
  • Revenue Share
This functionality is implemented in Mocean for Networks only!
The setPublisherRevenueShare method allows user to set a custom revenue share for an existing publisher.
A user may get a revenue share value for the specific publisher using the getPublisherRevenueShare method.

User Balances

Default user balance

Once a user is created a balance is assigned to him. This is a default balance. It can be replenished with the specified amount using the addFundsToUserBalance method . The funds can be added for the specified network (they will be available in this network only). If no network is specified, the funds will be added to the balance for the network you are working in (defined from the project url).

NOTE: Permissions are essential for adding funds to balances. A Network Owner/Manager is able to replenish his own and other users' balances in the network and its subnetworks.
Unrestricted User Balance

A user may also have an unrestricted balance alongside with the default one. In UI the unrestricted balance is assigned to a user once an order is created with the unrestricted balance selected for an advertiser from the drop-down. Unrestricted balance can be created via SOAP API as well using the createUnrestrictedUserBalance.

Insertion Order Balance

Once an Insertion Order is uploaded to fund advertiser ads, the insertion order balance is created for the user. A new insertion order can be created through the createInsertionOrder method. It can be replenished through the same createInsertionOrder method where the desired amount to add or subtract and the ID of the existing IO balance can be specified. The specified amount will be added to/subtracted from the IO balance.

If a user does not have any IO balance yet, when creating an Insertion Order via SOAP no balance ID can be specified. A new balance will be created then. Its ID will be returned in the response.

To create an Insertion Order two more user profiles should be created:

  • Sales Person - a person responsible for the sale of media in the network.
Here you may find the methods to create, edit, delete a sales person and to get sales person's data (name, IDs).
  • Account Manager - a person managing user's accounts.
Here you may find the methods to create, edit, delete an account manager and to get his data (name, IDs).

The list of all Insertion Orders in the network can be obtained through the getInsertionOrders method. The getInsertionOrder method allows users to get the information on the specified insertion order, that is its amount, the ID of a sales person assigned to it, IO file name and URL, user account ID, network ID and user balance ID it belongs to. The getInsertionOrderFile method allows users to get the insertion order file for the specified Insertion Order. The file is returned encoded in the base64 format and needs decoding via any Base64 decoder to save it in the original format.


Thus, a user can have three balances in the network.

To get the list of all balances existing in the network/for the specified user account use the getUserBalances method. The default balance will be shown with isDefault=true. The unrestricted balance has isInfinite=true. The insertion order balance has both isDefault=false and isInfinite=false.

Site/App & Zone Management

Picture below helps to understand the place of sites/apps and zones in Super-Network and its SubNetworks.


Network Owners, Managers and Publishers are able to manage sites/apps and its zones if they have the appropriate permission enabled.

Site/App Management
  • Create Site/App
In order to create a site/app the createSite method is to be used. While creating a new site/app the user may need such methods as getNetworks, getMobileEnvironments, getSiteAttributes, getChannels and getCategories to identify the network he is allowed to create a site/app in and get the ID of platforms, attributes (custom fields), channels (content verticals), and categories available in the network respectively.
If you know the category ID and would like to get the category name, you may use the getCategory method.
To find out the channel name (by its ID) use the getChannel method.
  • Copy Site/App
A new site/app can be created on the base of the existing one with the same settings using the copySite settings. To identify the site/app to be copied, the getSites can be used. The getSite can be helpful for the user too in case he knows the site/app ID but would like to ascertain its data.
  • Edit Site/App
If the user would like to change the existing site/app settings, he may use editSite and propagate the form with new data.
  • Delete/Undelete Site/App
A site/app can be deleted as well as restored (un-deleted) using deleteSite or undeleteSite respectively.
To single out the site/app the user would like to delete/restore (un-delete), he may use getSites for getting existing sites/apps or getDeletedSites for getting sites/apps that have been deleted.
  • Approve/Decline Site/App
This functionality is implemented in Mocean for Networks only!
Network Owner, Manager and Publisher can approve sites/apps (using approveSite) as well as decline them (via declineSite).
  • Competitive Settings
A user may set up keywords and URLs filters for a site/app to filter competitors' ads by. addCompetitiveKeywordFilter/ setCompetitiveKeywordFilter and addCompetitiveAdFilter/ setCompetitiveAdFilter can be used for this purpose.
  • Site/App Blocking
Apps/Sites can be blocked by users with appropriate permissions using the addBannedSites method or setBannedSites method (the latter resets all the previously made settings if any).
App/Site can be un-blocked using the deleteBannedSites method.
  • Suspended Url
A user may set suspended URLs for the network using the addSuspendedUrls method or the setSuspendedUrls method. The setSuspendedUrls method allows user to add suspended URLs instead of the existing one(s). To obtain all the network IDs the getNetworks method can be used.
The getSuspendedUrls method allows user to get the suspended URLs existing in the network.
A suspended URL can be deleted from the network using the deleteSuspendedUrl method.
  • Get Site/App Related Information
• If you know the site ID and would like to get the full information about the site/app, you may use the getSite method.
• If you would like to get all the sites IDs available in the network accompanied with the detailed information about each of them, you may use getSites. Sites/apps that have been deleted can be returned by getDeletedSites.
getCompetitiveKeywordFilter and getCompetitiveAdFilter methods return information about competitive ad filters set for the site/app.
getSiteChannels and getSiteCategories allows users to get information about content verticals and ad categories set for the specific site/app.
getSiteAttributes returns all the custom fields (attributes) that can be set for a site/app within the network.
• The getMobileEnvironments method returns mobile platforms available for the specific networks, such as Mobile Sites, Android app, Blackberry app, iPhone app, Microsoft app, or any other custom mobile platform.
• The getBannedSites method allows users to get the list of blocked apps/sites for the network.
Zone Management

Zones allow for the assignment of different ad types, placements and pricing within the sites/apps and content over a network.

The default zone with $0-valued Min Rate for CPM, CPC and CPA is created automatically for every site/app when the site/app is created.

  • Create Zone
The createZone method allows for adding new zones for the specific site/app. A list of sites/apps a new zone is able to be added to can be obtained via getSites.
If there are custom fields at the zone level, values for them should be provided within the <attributes> element while adding a new zone. To get the information about all zone attributes within the network, getZoneAttributes can be used.
  • Copy Zone
If you need to have two or more zones with the same settings, you may create a zone (or choose from existing ones) and copy it by copyZone providing a new zone with a new name.
  • Edit Zone
To change settings of the existing zone, the editZone method can be used.
  • Delete/Undelete Zone
Using deleteZone or undeleteZone, the specific zone can be deleted or restored (un-deleted) respectively.
To select the zone for deleting/restoring (un-deleting), getZones can be used for getting ID's of zones that haven't been deleted accompanied with its settings, or getDeletedZones for getting the information on deleted zones.
  • Get Zone Related Information
• If you know the zone ID and would like to get the information about the zone, you may use the getZone method.
• To get a list of all zones available for the specific site/app, getZones should be used. Zones that have been deleted may be accessed by getDeletedZones.
• Note that ads are not served on your site/app until the Site/App is activated by implementing the appropriate code for your site/apps zone. The install code of different script types for the specific ad zone can be accessed through getZoneInstallCode.
• Information about custom fields (attributes) at the zone level can be obtained via getZoneAttributes.

Order Management

The following picture reflects how Targeting, Placement, Order and Line Items are linked together.

A user may have several orders in the network. Each order should have separate line items created. Under each line item, delivery settings can be defined and several creatives can be created.

Targeting and Placement groups can belong to a particular user as well as to a Network. NOTE: Propagating targeting/placement groups to the entire network is available to network managers only!

• If a targeting/placement group is set with Network Wide enabled, it can be used by all advertisers/managers that can manage orders in the network.
• Targeting/Placement groups saved by a specific account will be available for all line items under that account.

When targeting and placement groups are defined, a user can assign them to his line items.

SOAP API allows users to create a new order for the network as well as to edit, copy or delete/restore (un-delete) existing orders.

  • Create Order
A new order can be created through the createOrder method.
To create an order, specify in the proper request lines a name for it, start and end dates, attributes' names and values (to get these data you may use the getOrderAttributes method).
Then set it as House OR Test if needed. Only one of these items can be set as 'True'.
Set daily and total limits at the order level. Enable the Smooth Delivery option if needed by setting the smoothDelivery parameter to 'true'. NOTE: Smooth Delivery can be enabled only if endDate and at least one of the total limits (shows/clicks/actions/money) is defined. If Smooth Delivery is enabled, the daily limits will be calculated automatically.
Specify balance ID if necessary. It can be found through the getUserBalances by user account ID or network ID. If not specified the user default balance will be used.
Optionally you may specify the ID of the network or account ID your order will be assigned to. If not specified the order will be created for the network subdomain specified in the SOAP project name or to the account defined by the api key.
In the response you will get the new order ID with all the settings made for the order.
The information on an order can also be received through the getOrder method by the order ID.
Or the list of all orders existing in the network can be obtained using getOrders method by network ID or account ID. If none of them is specified, the orders will be returned for the user account defined by the api key.
  • Edit Order
The editOrder method allows users to make changes to an order in reference to its name, end date, attributes, limits and smooth delivery. The following parameters should be specified without changes:
  • Start date;
  • House Order ('isHouse' element in the request form);
  • Test Mode ('isTest' element in the request form).
  • Copy Order
An order can be copied with the copyOrder method. Specify the ID of the order you would like to copy, a new name for it and advertiser's data if you would like to assign a new order to another advertiser. All the other settings will be inherited from the specified parent order. To change them you may use the editOrder method described above.
  • Delete Order
An order can be deleted using deleteOrder method. Send the request with the ID of the order you would like to delete and receive "True" in the response.
  • Undelete Order
To restore (un-delete) the deleted order, use the undeleteOrder method. Send the request with the ID of the order you would like to restore (un-delete) and receive "True" in the response.
  • Get Order Related Information
• If you know the order ID and would like to get detailed information about the order, you may use the getOrder method.
• If you would like to get all the orders IDs existing in the network accompanied with the detailed information about each of them, you may use getOrders. Orders that have been deleted can be returned by getDeletedOrders.
getOrderAttributes allows you to obtain all the custom fields (attributes) which can be set for an order within the network.

Line Items can be assigned to saved orders. But before proceeding to the line item creation let's find out more about how Targeting and Placement groups should be created as their IDs are needed in the line item creation form.

Targeting Settings
Create Targeting Group

To create a new targeting group use the createTargetingGroup method. It enables creating a new targeting group for a specific network. In the response you will get the id of the newly created targeting group.

This targeting group has no setting inside. All the necessary settings can be added one by one using the methods below.

Location
Location Targeting can be set using the methods:
The list of existing location targeting items can be obtained using the corresponding SOAP get-methods:
The information about existing location targeting item can be obtained using the corresponding SOAP get-methods:
Device
Device Targeting can be set using the methods:
The list of existing device targeting items can be obtained using the corresponding SOAP get-methods:
The name of existing device item can be obtained using the methods:
Audience
Audience Targeting can be set using the methods:
The list of existing audience targeting profiles, behaviors and segments can be obtained using the corresponding SOAP get-method:
Scheduling
Scheduling Targeting can be set using the method:
In SOAP start/finish fields determine the first and the last hour included to schedule. Each hour has a unique number in SOAP.
0 for 00:00-00:59 (12:00am-12:59am)
1 for 01:00-01:59 (01:00am-01:59am)
...
11 for 11:00-11:59 (11:00am-11:59am)
12 for 12:00-12:59 (12:00pm-12:59pm)
13 for 13:00-13:59 (01:00pm-01:59pm)
..
22 for 22:00-22:59 (10:00pm-10:59pm)
23 for 23:00-23:59 (11:00pm-11:59pm).
Thus when setting start=22 and finish=23 your ad will be delivered for 2 hours from 22:00:00 till 23:59:59.
To make an ad run 24 hours per day set start=0 and finish=23 for the ad to be delivered from 00:00:00 till 23:59:59.
Equal start/finish values will make your ad run just for one hour: start=10 and finish=10 means that the ad delivery period is from 10:00:00 till 10:59:59
NOTE: "Start" value can not be greater than "finish". Thus, it is not allowed to set start=23 and finish=2. Such a period should be split into two ones for two different days i.e. start=23 and finish=23 for one day and start=0 and finish=2 for the next day.
The list of existing time zones can be obtained using the getTimeZones method.
Custom Parameters
Custom Parameters Targeting can be set using the method:
The list of existing custom parameters can be obtained using the corresponding SOAP get-method:
Parameters Existence Targeting
Parameters Existence Targeting can be set using the method:
Manage Targeting Group

To check if all the desired settings were made correctly or simply get the information on the specified targeting group, use the getTargetingGroup method.
If any elements need corrections use the appropriate set-method to rewrite the settings for this targeting group.
You may also edit a targeting group using the editTargetingGroup method but only to change its name and time zone.
To get the list of all targeting groups for the network, use the getTargetingGroups method. Specify an order ID in the request to get the targeting group(s) for an individual order.
You may delete a targeting group thru the deleteTargetingGroup method.

Placement Settings
Create Placement Group

To create a new placement group use the createPlacementGroup method. In the response you will get the ID of the newly created placement group with its name, network ID it is assigned to and user's account ID it belongs to.
This placement group is empty inside. To add bindings to it use the setPlacementBindings method. It allows to specify the networks/subnetworks/sites/zones either for negative or positive placement (that is to exclude or include them from the placement settings). NOTE: Using the set-method removes any other previously made bindings. So if any element needs changes use the set-method.
To add more settings use the addPlacementBindings method - new bindings will be added to the existing ones without any being taken out.

Manage Placement Group

A placement group name can be edited thru the editPlacementGroup method. To get the information for a placement group use the getPlacementGroup method that allows to receive all the bindings for the specified placement group in one response.
To get the list of all placement groups in the network use the getPlacementGroups method. Specify the order ID to get the list of Placement Groups belonging to one order.
To delete a placement group use the deletePlacementGroup method. Please note that a placement group can not be deleted if it is assigned to any line item.

Line Item Management
Create Line Item
When an order is created assign a line item to it using the createLineItem method.
It will contain the main settings for the ad delivery - status, targeting, placement, delivery, creatives/ad feeds. Several line items can be created for a single order. Specify the necessary settings in the request form as described in the documentation.

Enter a name for the new line item, start and end dates in accordance with the XML Schema language specification (e.g., 2002-10-10T12:00:00-05:00), daily and total limits that should be integer and positive numbers with total limits greater than daily ones.

Then, specify custom attributes if any exist for line items in the network (you can find it out thru the getLineItemAttributes method). If the line item attribute is created as a required one it is obligatory for entering in the form.

Assign a category to your line item if necessary to specify its type. The list of categories existing in the network is available thru the getCategories method.
Targeting And Placement
Choose targeting and placement groups for your line item entering the IDs in the appropriate lines. The list of existing groups can be obtained through the corresponding getTargetingGroups or the getPlacementGroups methods. Only one targeting/placement group can be chosen per one line item.
Define an optimization type choosing among EVEN, WEIGHTED (weight based) or PERFORMANCE (CTR based).
Specify if the creative should be shown within the network only by entering NETWORK_ONLY for showOn element, or for other networks only specifying EXTERNAL_ONLY here. Enter ANYWHERE for both options.
Specify the order ID the line item will belong to.
Set the line item source: to set it to a direct creative enter "false" for <isExternal> flag; to make it a 3rd Party Ad Feed enter "true" here.
Send the request and receive the ID for the newly created line item and its data.
Domain Blocking
The system allows to prevent your ad from the delivery on some domains. The list of domains to block can be set through the setBlockedDomains. You can view the set blocked domains for the line item via the getBlockedDomains.
Blocking/Invalid
The system allows to prevent your ad from the delivery on some domains. The list of domains to block can be set through the setBlockedDomains. You can view the set blocked domains for the line item via the getBlockedDomains.
Invalid settings can be set at the line item level. While creating a line item enable the invalid settings you wish to apply to your line item:
pixelTracking - Set to "true" if pixel tracking is required. In this case an impression is counted as valid only if the pixel is rendered on the mobile device end.
ipCheck - Set to "true" if the IP check is required. In this case, if the IP address of the impression and the click do not match, the click is marked as invalid.
uaCheck - Set to "true" if the UA check is required. In this case, if the UA of the impression and the click do not match, the click is marked as invalid.
targetingCheck - Set to "true" if the targeting check is required. Ad Server will check line item targeting against the click, if they don't match the click marked as invalid.
doubleClick - Set to "true" to mark all clicks after the initial click per impression ID as invalid.
Delivery
Then the delivery settings should be specified. Enter a goal price type (CPC, CPM, CPA) and the price you will pay. Enter a priority level specifying the priority level ID, rank and percent. You may obtain the information about existing priority levels using the getPriorityLevels or getPriorityLevel methods. NOTE: To find out more about priority levels, please follow Priority Levels.

Enable smooth delivery if necessary by entering "True" for this element in the form. NOTE: Smooth delivery functionality allows for calculating optimal daily limits for the line item delivery using efficient algorithms. Please, keep in mind that Smooth Delivery can be enabled only if the following requirements are met:
  • end date defined;
  • at least one of the total limits is defined (shows/clicks/actions/money).
If your ad is intended for adults only set "isOver18" flag to "true".
Specify the frequency capping that is the number of ad impressions that can be delivered per a certain period of time. Several cappings can be specified using <item> (integer) for each.
NOTE: Frequency capping can be set to a line item and a creative. If set for both the creative level frequency capping is used. If defined for the line item and a single creative the creative will use its frequency capping while to the remaining creatives impressions the line item frequency capping is applied.

An auto-conversion optimization can be set to the existing line items using the setConversionOptimizationParams method. Specify a line item ID and type. Type can take two values:
  • '0' - optimization is disabled (the other parameters values are default),
  • '1' - optimization is enabled.
If the type is '1' then specify values for other parameters.
To obtain the conversion optimization parameters for the specific line item use the getConversionOptimizationParams method.
Creatives
Creatives can be added to the existing line items using SOAP API methods.
The createCreative method is used to generate a new creative. Specify a line item ID to assign it to the specific line item. Enter its name and type. Creative can be created as one of 5 types:
  • text ad (TEXT),
  • graphic ad (IMAGE),
  • richmedia (RICHMEDIA),
  • native ad (NATIVE) or
  • video ad (VIDEO).
Enter one of the values for the <adType> element.

Specify the landing page URL for the creative.

The optional <adSubType> element should be populated for richmedia or video ads. For richmedia creative specify the text or image. For video ads select VAST2, VAST3 or VAST 3L.

For text creative enter the ad text into <text> tag. For richmedia ads, HTML or script code should be here. In case of VIDEO creative, enter CDATA-wrapped VAST XML tag of a version specified an <adSubType> tag.

Enter a landing page ID if clicking on the creative should take a user to a MoceanMobile-hosted landing page.

Specify the creative weight with up to 3 digits. When delivery type is set to "Weighted", this value will be used to determine which creative to serve.

Specify width and height of the creative in pixels to ensure the ad will be running in the appropriate ad spots set up by publishers. It make sense for Rich Media Ads only.

If generating a graphic creative, an image has to be uploaded. It can be done in one of the following ways:
  • Store the file externally and set <referenceUrl> to point to the full file URL (i.e. http://domain.com/path/to/file.jpg).
  • Convert the file content to the Base64-encoded string and put it inside the <binaryContent> tag.
  • Use MIME multipart message and set <referenceUrl> to cid:{contentId}.
  • An externally-hosted banner can be used. So enter a full URL in to the <externalUrl> tag.
Thus, for graphic ads one of the optional elements - <referenceUrl> OR <binaryContent> OR <externalUrl> - should be specified to upload an image. Otherwise, "Attachment required" warning message appears and the creative can not be saved.

For the image in <sizes> tags specify text, clickUrl, track (corresponds to Pixel URL), width and height.
Specify as many sizes as you need for one image.

Several images can be uploaded to one line item adding several <item> tags under <images>.
Or more images can be added to an existing line item through the addCreativeImages method.
NOTE: The sizes for images under one creative should differ. The maximum allowed size is 4000x4000px and the minimum allowed one is 1x1px. The image can not exceed 2Mb.
Set the frequency capping at the creative level, that is the number of ad impressions that can be delivered per a certain period of time.
NOTE: Frequency capping can be set to a line item and a creative. If set for both the creative level frequency capping is used. If defined for the line item and a single creative the creative will use its frequency capping while to the remaining creatives impressions the line item frequency capping is applied.
Based on the native ad template specify the required assets into <assets> tag. What assets which template requires you can find using the getNativeAssetTypes method.
If any settings need to be changed the editCreative method can be used.
NOTE: Please keep in mind, while editing a native creative, you should specify all the necessary existing assets. Otherwise, all non-mentioned assets will be removed. To get all the assets of the specific creative, getCreativeAssets method can be used.
To change only one native asset of the specific creative you may use the editCreativeAsset method.
A new creative can be created by copying an existing creative using the copyCreative method. Specify the ID of the creative you would like to copy, a new name for it and line item ID if it differs from the creative parent line item. All the other settings will be inherited from the specified parent creative. To change them you may use the editCreative method. To obtain the list of IDs of the line items for the specific order use the getLineItems method.
A creative can be started using the startCreative method. A running creative can be paused by using pauseCreative method.
A user may delete an image from the creative using the deleteCreativeImage method.
To obtain the list of all images for one creative use the getCreativeImages method.
To get the information on the creatives under a specified line item use the getCreatives method. To find out the specified creative data (by its ID) use the getCreative method.
To get a list of available landing pages for the user account use the getLandingPages method. If you know the landing page ID and would like to get detailed information about this page, you may use the getLandingPage method.
To delete a creative use the deleteCreative method. The list of deleted creatives can be viewed through the getDeletedCreatives method. A deleted creative can be restored via the undeleteCreative method.
AdFeed Management
SOAP API methods allow to create external creatives for a line item. They are available to users with Manage Ad Feed permission enabled (see User Profile Permissions section). Users are allowed to add feeds based on their 3rd party ad feed usage and relationships.
Create External Creative
To create an external creative use the createExternalCreative method.
In the request form you should specify the ID of a line item the ad feed configuration is being created for, the feed ID you create the creative for, name and weight for your creative.
Optionally specify the reporting config ID for your creative and parameters' name(-s) and value(-s). The list of all existing reporting configurations for external feeds can be obtained with the getExternalReportCredentials method. The list of all existing ad feed parameters can be obtained with the getExternalFeeds method.
To obtain the information on existing custom an feed parameters use the getCustomAdFeedParameters method.
Manage External Creative
A newly created ad feed creative is automatically set run, <is Paused> is returned as False. To pause the creative use the pauseExternalCreative method. To start a creative the startExternalCreative method exists.
You can obtain the list of creatives assigned to an individual line item using the getExternalCreatives method. To get the data for an individual external creative use the getExternalCreative method.
An external creative can be edited through the editExternalCreative method or deleted using the deleteExternalCreative method. The list of deleted external creatives can be obtained via the getDeletedExternalCreatives method.
Deleted external creatives can be restored through the undeleteExternalCreative method.
A new external creative can be created by coping an existing external creative using the copyExternalCreative method. Specify the ID of the external creative you would like to copy, a new name for it and line item ID if it differs from the creative parent line item. All the other parameters will be inherited from the specified parent creative. To change them you may use the editExternalCreative method. To obtain the IDs of the line items for the specific order use the getLineItems method.
Manage Line Item
A newly created line item has the 'Pending' status and is not active until it is started.
A line item with the 'Pending' status can be approved or declined by a user with appropriate permissions through these corresponding methods - approveLineItem and declineLineItem.
An approved line item can be started using the startLineItem method. A running line item can be paused by using the pauseLineItem method.
To view the list of existing line items with all their settings, use the getLineItems method. The settings of an individual line item can be obtained through the getLineItem method.
If any settings need to be changed the editLineItem method can be used. NOTE: Please keep in mind, while editing the line item, setting frequency capping for the line item will lead to removing the frequency capping previously set for its creatives.
A new line item can be created by copying an existing line item using the copyLineItem method. The new line item in this case inherits all the settings from the original line item. If necessary any settings can be changed through editLineItem.
A line item can be deleted as well as restored (un-deleted) using deleteLineItem method or undeleteLineItem method respectively.
To single out the line item the user would like to delete/restore (un-delete), he may use getLineItems method for getting existing line items or getDeletedLineItems method for getting line items for an order that have been deleted.

Statistics Reporting

The reporting API methods allow to obtain the statistics data for the network objects performance.

The data available to users is determined by user permissions within his role.

  • Network Owners can view data for all sites/zones and orders/line items in the network.
  • Advertisers can view data for their own orders only but for all sites and zones.
  • Publishers (Mocean for Networks) can view data for all orders in the network but only for his sites and zones.

In the request form the start and end dates of the reporting period should be specified.
NOTE: Data for "toDate" day won't be included into the report.

When using reporting SOAP methods keep in mind that an element of 'Array' type may contain several <item> elements with different integer values in them to obtain data for each of them.

E.g.: In 'getCampaignReportByLineItem' send several order IDs to obtain the data for line items of the specified orders.

<orderIds>
    <!--Zero or more repetitions:-->
    <item>123456</item>
    <item>123789</item>
    <item>123654</item>
</orderIds>

The following general reporting methods are available for getting information about reports, either custom reports or Forecasting/Inventory Management reports. These methods allow you to run a report configuration, get its status (whether it is executing or completed) and get URL where the completed report can be picked up.

The following reporting methods return data on publisher's activity including the amount of money earned:

To get the reporting data including external statistics on publisher's activity including the amount of money earned use the following methods:

The following reporting methods return data on advertiser's ad campaign(-s) activity including the amount of money spent:

To get the reporting data including external statistics on advertiser's ad campaign(-s) activity including the amount of money spent use the following methods:

To get reporting data for both publisher's and advertiser's budget the following methods are intended:


Forecasting Reports

Forecasting reports are also available through SOAP API. You can get the forecasting data:

A Forecasting report is obtained for a year period ahead.

Pacing Report

You can get the pacing report using the following SOAP API methods:

Best Practices

In general, the SOAP API must be considered a rigid, but ever-updating API. Any methods or parameters that are currently present will not change without a new version or notification well in advance. This does not mean that the API, itself, won't change. Any requester that is using methods currently will not have to worry about updates breaking those methods. Any updates to the SOAP API will remain backwards compatible. If new functionality is added, the requester does not need to be aware of the changes until they are required to do the work. This means that you can cache the WSDL and it will be compatible until we give notice of a breaking change.

See IBM's article on SOAP API updating: http://www.ibm.com/developerworks/webservices/library/ws-version/

From the document:

It can be argued that, when the interface to a service changes in a non-backwards-compatible way, in reality an entirely new service has been created. In such a case, unless implementations of the first interface continue to exist, the preexisting service is, in effect, discontinued. From the client's perspective, a service is no more than an interface and some non-functional qualities (such as trust and QoS attributes) that it may claim to exhibit; thus, if the interface to a service changes in a non-backwards-compatible way, it no longer represents an instance of the original service, but is rather a completely new service.

From this point of view, an interface version is always backwards-compatible with the preexisting interface. This can mean either that operations are added while all prior operations are maintained, or that existing operation signatures are changed in a manner that is compatible with the original interface (opportunities for such changes are limited). Further, it is reasonable to expect that earlier versions of a service are not forward-compatible with later versions. Therefore, if a service interface is changed in a manner that is not backwards-compatible, it is not a version of the earlier service; it is a new service.

Mocean Mobile's SOAP API will not make any breaking changes unless we give notification of the changes. Any updates to the SOAP API that contain non-breaking changes will occur as they happen. It is up to the end library to be aware that changes may happen and that those changes won't cause any current services to break.

Personal tools