Campaign Overview API
Given an advertiser email address and date range, this retrieves campaign metrics for all active campaigns. Data returned is in XML and includes the following:
- Campaign Name
- Date
- Number of impressions
- Number of views
- Total number of click-through events
- Total number of interactions
- For each interaction, the interaction name and count
- Interaction rate
Please note that totals for the columns are not provided.
Request URL
To retrieve the campaign overview report, make a request to the following URL: http:///jivox/serverAPIs/externalReporting/campaignOverviewReport.php
Parameters
The request URL supports the following parameters:
| Parameter | Description |
|---|---|
| apiId | (Required) ID of the API. |
| apiKey | (Required) Authentication key. |
| apiVersion | (Required) Version number of the API for which authentication key is generated. |
| publisherId | (Required) ID of the publisher or agency for which authentication key is generated. |
| emailAddress | Email address of the advertiser. |
| startDate | Start of date range for which the report is required. |
| endDate | End of date range for which the report is required. |
| externalId | External identifier for a campaign (entered when the tag is generated for a campaign). If this is provided then emailAddress is ignored and only the campaign (or campaigns) with the matching external identifier are included in the result. |
| campaignType | (Optional) Filter campaigns by campaign type. Valid values include web, directory. |
Example
Using cURL (this command includes hard returns for readability):
xxxxxxxxxxcurl -d 'apiId=jivox.externalReporting&apiKey=MyAPIKey&apiVersion=2.0& publisherId=939&emailAddress=advertiser@example.com& startDate=2011-01-01&endDate=2011-06-30' http:__testserver.jivox.com_jivox_serverAPIs_externalReporting_campaignOverviewReport.phpServer Success Response
In case of success, the server returns the following response:
xxxxxxxxxx<jivoxServerResponse><result>SUCCESS<_result><campaigns><campaign ><id> campaign_id <_id><name> campaign_name <_name><type>campaign_type<_type><status>campaign_status<_status><thumbnail>thumbnail_url<_thumbnail><advertiserName>advertiser_name<_advertiserName><startDate> start_date <_startDate><endDate> end_date <_endDate> <records><record><date> date <_date> <impressions>number_of_impressions <impressions> <adStart>number_of_ad_starts <_adStart> <numClickthrus>total_number_of_clickthrus<_numClickthrus><numInteractions>number_of_interactions<_numInteractions><interactions><interaction><name> interaction1_name <_name><count> interaction1_count <_count><_interaction><interaction><name> interactionN_name <_name><count> interactionN_count <_count><_interaction><_interactions><universalInteractionRate>iab_universal_interaction_rate<_universalInteractionRate><averageDwellTime>average_dwell_time<_averageDwellTime> <completionRate>ad_completion_rate<_completionRate> <clickThroughRate>click_thru_rate<_clickThroughRate> <interactionRate>interaction_rate<_interactionRate><_record><record><_record><_records><_campaign><campaign><_campaign><_campaigns><_jivoxServerResponse>Fields in the server response XML are as follows:
campaign_type: Filter campaigns by campaign type, from the following:
xxxxxxxxxx'Web Campaign'Legacy campaigns may show the following deprecated types:
xxxxxxxxxx'Viral Campaign', 'Directory Listing Campaign', 'Website Campaign', 'Email Campaign', 'External Campaign', 'Social Media Campaign'campaign_status: The current state of the campaign, from the following:
xxxxxxxxxx'Running', 'Approved'Legacy campaigns may show the following deprecated states:
xxxxxxxxxx'Completed', 'Canceled', 'Paused', 'Created', 'Activated', 'Rejected'In most cases campaigns will be in the "Running" state.
- campaign_thumbnail: The active image provided for the campaign. This is only valid for video ads and returns the thumbnail URL.
- campaign_start_date: The campaign launch date.
- campaign_end_date: The campaign end date.
- record_date: The date on which the event was recorded. If a campaign ran 30 days and recorded events on each day there will be 30 record entries in the xml.
- record_impressions: Number of times the ad player was loaded on the publisher page.
- record_num_clickthrus: Number of times users clicked anywhere on the ad, not including clicks on the interactivity features.
- record_num_interactions: Number of user actions, including clicking on any part of the ad, clicking or rolling over on the Interactivity Panel, and clicking on any interactivity option.
- record_completionRate: Number of times the ad video ran to completion as a percentage of the number of impressions.
- record_clickThroughRate: The click-through rate: the number of clicks divided by the number of impressions.
- record_interactionRate: The interaction rate: the number of interactions divided by the number of impressions.
- record_universalInteractionRate: The percent of users who purposely enter the frame of an ad continuously for at least 0.5 seconds or more. Universal Interaction Rate (UIR) as defined by the IAB refers to the number of times a user's mouse enters the frame of an ad and is active (not parked) for 0.5 seconds or longer (maximum of one interaction per load) divided by the number of times an ad fully loads on the page (maximum of one ad load per page).
- record_averageDwellTime: The average amount of time users spent on the ad. Universal Interaction Time (UIT) as defined by the IAB is the average length of a time that a user's mouse enters the frame of an ad and is active (not parked) for 0.5 seconds or longer and ends when the mouse leaves the ad frame, or at 60 seconds, which ever happens first.
- interaction_name: Name of the interaction.
- interaction_count: Total number of this type of interaction.
Was this page helpful?