ayeT-Studios Advertiser API Documentation (V1.2)
Deprecation Notice
Attention: As of 2016-05-21, this Advertiser API is deprecated.
It will continue to work with the current featureset, but if you plan to integrate with our Advertiser API in the future, please follow our APIv2 documentation.
Updates
2016-05-21: Deprecated APIv1
2016-04-27: Added new function, "reporting/summary_daily"
2015-10-13: Added new function, "reporting/summary"
2015-07-17: Extended "campaign/quote" to also return targeted traffic and est. daily installs
2015-07-16: Added identifier (campaign related) support for the api
Introduction
Our API allows our clients to automate most of their workflow.This includes basic account information and full campaign management which allows tight integration of our services in your own website.
We use a REST API with JSON encoded data.
The examples in this documentation rely on PHP with mod_curl and have to be adapted for other languages if required.
Topics
- Obtain API Key and Getting Started
- Account Module
- Campaign Module
- Reporting Module
- Appendix I: Error Codes
1. Obtain API Key and Getting Started
To obtain your API Key, log into your dashboard.
In the sidebar on the left you'll find the menu entry Account Settings where you will find a menu with the subitem API Settings. It will show your current API Key and the option to renew your key if neccessary.
We've built a simple example function in PHP using mod_curl to send a request to our server and fetch the response. This function will be used throughout the documentation:
function ayetRequest($command, $requestData = array()) {
$apiKey = "XXX"; // TODO: Replace with your API key
if (!is_array($requestData)) {
$requestData=array();
}
$requestData['apiKey'] = $apiKey;
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_URL => 'https://www.ayetstudios.com/api/'.$command,
CURLOPT_POST => 1,
CURLOPT_POSTFIELDS => $requestData)
);
if (($responseData = curl_exec($curl))===false) {
curl_close($curl);
/* echo "cURL error: ".curl_error($curl); */
return null;
}
return json_decode($responseData, true);
}
2. Account Module
Get Account Details
Summary:
Retrieves information about the associated account, including available funds.Call:
account/details
Parameters:
none
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("account/details");
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success // string, either success or error
[accountData] => Array
(
[accountId] => 6 // integer, the ID of this account
[email] => my@mail.com // string, email address associated with account
[runningCampaigns] => 2 // integer, number of currently running campaigns
[pendingCampaigns] => 0 // integer, number of currently pending (== paused) campaigns
[completedCampaigns] => 0 // integer, number of completed or terminated campaigns
[tokens] => 4100 // integer, available tokens on this account
)
)
3. Campaign Module
List all campaigns
Summary:
Retrieves all campaigns associated with this account.Call:
campaign/list
Parameters:
ARRAY status (optional, JSON array, if set, only returns campaigns with the given statuses [pending, running, completed, review])
STRING identifier (optional, if set, only returns campaigns matching the identifier)
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("campaign/list", array('status' => json_encode(array('running', 'pending')), 'identifier' => 'customer1'));
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[numCampaigns] => 2
[campaignData] => Array
(
[0] => Array
(
[campaignId] => 87 // integer, unique id for this campaign
[identifier] => customer1 // string, the value supplied when creating the campaign
[packageName] => com.xxx.yyy // string, Play Store package name
[appName] => My Cool Calculator // string, English (US) title of the app
[appIcon] => https://lh5.ggpht.com/xx=w140 // string, URL to app icon
[targetCountries] => US, GB // string, country codes, empty for worldwide
[totalDownloads] => 90 // integer, total campaign volume
[remainingDownloads] => 65 // integer, remaining campaign volume
[reservations] => 3 // integer, users currently downloading app
[tokensPerDownload] => 1 // integer, price charged per install
[downloadRate] => 2400 // integer, maximum downloads per day
// 24-2400, 2400 means "unlimited"
[isRetention] => 0 // integer, 0 for standard campaigns, 1 for HR campaigns
[tracking] => standard // standard or custom_s2s (requires permissions)
[redirectUrl] => // empty for standard campaigns, the tracking url for s2s
[status] => running // string, current campaign status
// pending, running, terminated
[created] => 2014-02-08 02:40:59 // string, creation date
)
[1] => Array
(
[campaignId] => 286
[identifier] => customer1
[packageName] => com.xxx.zzz
[appName] => My Cool Watch
[appIcon] => https://lh6.ggpht.com/xx=w140
[targetCountries] =>
[totalDownloads] => 100
[remainingDownloads] => 14
[remainingRetentions] => 94 // integer, only available on HR campaigns
[reservations] => 0
[tokensPerDownload] => 1.1
[downloadRate] => 2400
[isRetention] => 1
[tracking] => standard // standard or custom_s2s (requires permissions)
[redirectUrl] => // empty for standard campaigns, the tracking url for s2s
[status] => running
[created] => 2014-03-01 16:25:01
)
)
)
Get specific campaign
Summary:
Retrieves a specific campaign identified by its unique campaignId.Call:
campaign/get
Parameters:
INTEGER campaignId (required, the id of the campaign to be returned)
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 305 | Campaign does not exist. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("campaign/get", array('campaignId' => 286));
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[campaignData] => Array
(
[campaignId] => 87 // integer, unique id for this campaign
[identifier] => customer1 // string, the value supplied when creating the campaign
[packageName] => com.xxx.yyy // string, Play Store package name
[appName] => My Cool Calculator // string, English (US) title of the app
[appIcon] => https://lh5.ggpht.com/xx=w140 // string, URL to app icon
[targetCountries] => US, GB // string, country codes, empty for worldwide
[totalDownloads] => 90 // integer, total campaign volume
[remainingDownloads] => 65 // integer, remaining campaign volume
[reservations] => 3 // integer, users currently downloading app
[tokensPerDownload] => 1 // integer, price charged per install
[downloadRate] => 2400 // integer, maximum downloads per day
// 24-2400, 2400 means "unlimited"
[isRetention] => 0 // integer, 0 for standard campaigns, 1 for HR campaigns
[tracking] => standard // standard or custom_s2s (requires permissions)
[redirectUrl] => // empty for standard campaigns, the tracking url for s2s
[status] => running // string, current campaign status
// pending, running, terminated
[created] => 2014-02-08 02:40:59 // string, creation date
)
)
Quote price per install
Summary:
Retrieves the price per install for a set of targeted countries.Call:
campaign/quote
Parameters:
STRING targetCountries (comma-seperated list of countries to target *)
STRING campaignType (optional, if set to "retention", the price for a high retention campaign is calculated)
* Available countries:
US, GB, CA, AU, DE, FR, IT, ES, NL, MX, IN, VN, JP, RU, PL,
MY, AT, BR, PH, ID, CO, CZ, RO, HK, GR, BG, TR, KR, PT,
UA, HU, TH, VE, CH, SA, SG, TW, MA, CL
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 301 | Invalid countries requested: $invalidCountryCodes. |
| 429 | Too many consecutive API requests, throttled. |
Example:
responseData = ayetRequest("campaign/quote", array('targetCountries' => 'US, DE'));
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[tokensPerInstall] => 1.15 // float, CPI in tokens for selected countries
[targetedTraffic] => 38 // integer, targeted traffic in percent
[minWorldwideInstallsPerDay] => 1754 // integer, min. est. worldwide installs/day
[maxWorldwideInstallsPerDay] => 3982 // integer, max. est. worldwide installs/day
)
Add a new campaign
Summary:
Creates a new campaign for a free Google Play application.Call:
campaign/add
Parameters:
STRING packageName (required, package name of the app (e.g. com.ex.app))
INTEGER numDownloads (required, the desired campaign volume, 20-10000 or 50-10000 for retention)
STRING campaignType (optional, if set to "retention", a high retention campaign is created)
STRING targetCountries (optional, comma-seperated list of countries to target *)
INTEGER downloadRate (optional, maximum number of downloads per day 24-2400)
STRING status (optional, initial status - "pending" (default) or "running")
STRING identifier (optional, an arbitary string which can be used to identify a customers campaign later)
STRING tracking (requires permission, "standard" or "custom_s2s")
STRING redirectUrl (requires permission, required for "custom_s2s" tracking campaigns)
* Available countries:
US, GB, CA, AU, DE, FR, IT, ES, NL, MX, IN, VN, JP, RU, PL,
MY, AT, BR, PH, ID, CO, CZ, RO, HK, GR, BG, TR, KR, PT,
UA, HU, TH, VE, CH, SA, SG, TW, MA, CL
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 102 | Missing parameter: packageName. |
| 102 | Missing parameter: numDownloads. |
| 102 | Missing parameter: redirectUrl. |
| 104 | Invalid parameter: tracking. |
| 105 | Invalid parameter: redirectUrl. |
| 301 | Invalid countries requested: $invalidCountryCodes. |
| 302 | Minimum campaign volume is 20 downloads. |
| 302 | Minimum campaign volume for retention campaigns is 50 downloads. |
| 302 | Maximum campaign volume is 10000 downloads. |
| 303 | Insufficient funds, $tokens available, $priceTokens required. |
| 304 | Selected app is not valid or not free. |
| 310 | Insufficient account permissions to create custom s2s tracking campaigns. |
| 311 | Invalid redirect url. |
| 312 | Required parameter {click_id} missing in redirect url. |
| 313 | Custom s2s tracking is not supported for high retention campaigns. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("campaign/add",
array(
'packageName' => 'com.example.app',
'numDownloads' => 50,
'targetCountries' => 'US, DE, GB, CA', // optional, default is worldwide
'downloadRate' => 300, // optional, default is unlimited (= 2400)
'status' => 'running' // optional, default is 'pending',
'identifier' => 'customer1' // optional, we set this to customer1 and can later filter our "get" commands
)
);
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[campaignData] => Array
(
[campaignId] => 290
[identifier] => customer1 // string, the value supplied when creating the campaign
[packageName] => com.example.app
[appName] => My Example App
[appIcon] => https://lh6.ggpht.com/xxxxx=w140
[targetCountries] => US, DE, GB, CA
[totalDownloads] => 50
[remainingDownloads] => 50
[reservations] => 0
[tokensPerDownload] => 1.15
[downloadRate] => 288
[isRetention] => 0
[tracking] => standard
[redirectUrl] =>
[status] => running
[created] => 2014-03-07 14:43:46
)
)
Edit campaign settings
Summary:
This command is used to edit one or multiple campaign settings (currently only downloadRate).Call:
campaign/edit
Parameters:
INTEGER campaignId (required, the id of the campaign to be edited)
INTEGER downloadRate (optional, desired download rate per day)
* Hint:
Valid input is 24-2400, where 2400 installs per day currently equal "unlimited".
Our system converts daily caps to hourly caps, so the actual download rate might differ (see example)
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 305 | Campaign does not exist. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("campaign/edit", array('campaignId' => 286, 'downloadRate' => 250));
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[campaignData] => Array
(
[campaignId] => 286
[identifier] => customer1
[packageName] => com.xxx.yyy
[appName] => Example App
[appIcon] => https://lh6.ggpht.com/xxxxx=w140
[totalDownloads] => 100
[remainingDownloads] => 45
[reservations] => 3
[tokensPerDownload] => 1.1
[downloadRate] => 240 // Hint: 250 was converted to 240 to represent
// a multiple of 24
[isRetention] => 0
[tracking] => standard // standard or custom_s2s (requires permissions)
[redirectUrl] => // empty for standard campaigns, the tracking url for s2s
[status] => running
[created] => 2014-03-01 16:25:01
)
)
Start a campaign
Summary:
This command starts a campaign which is currently in pending (= paused) state.Call:
campaign/start
Parameters:
INTEGER campaignId (required, the id of the campaign to be started)
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 305 | Campaign does not exist. |
| 306 | Only pending campaigns can be started, current status is $status. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("campaign/start", array('campaignId' => 286));
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[campaignData] => Array
(
[campaignId] => 286
[identifier] => customer1
[packageName] => com.xxx.yyy
[appName] => Example App
[appIcon] => https://lh6.ggpht.com/xxxxx=w140
[totalDownloads] => 100
[remainingDownloads] => 45
[reservations] => 3
[tokensPerDownload] => 1.1
[downloadRate] => 240
[isRetention] => 0
[tracking] => standard // standard or custom_s2s (requires permissions)
[redirectUrl] => // empty for standard campaigns, the tracking url for s2s
[status] => running // campaign is running now
[created] => 2014-03-01 16:25:01
)
)
Pause a campaign
Summary:
This command pauses a campaign which is currently running (new state will be "pending").Call:
campaign/pause
Parameters:
INTEGER campaignId (required, the id of the campaign to be paused)
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 305 | Campaign does not exist. |
| 306 | Only running campaigns can be paused, current status is $status. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("campaign/pause", array('campaignId' => 286));
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[campaignData] => Array
(
[campaignId] => 286
[identifier] => customer1
[packageName] => com.xxx.yyy
[appName] => Example App
[appIcon] => https://lh6.ggpht.com/xxxxx=w140
[totalDownloads] => 100
[remainingDownloads] => 45
[reservations] => 3 // downloads in progress can still be
// completed by users
[tokensPerDownload] => 1.1
[downloadRate] => 240
[isRetention] => 0
[tracking] => standard // standard or custom_s2s (requires permissions)
[redirectUrl] => // empty for standard campaigns, the tracking url for s2s
[status] => pending // campaign is paused now
[created] => 2014-03-01 16:25:01
)
)
Terminates a campaign
Summary:
This command terminates a campaign which is currently in paused state and does not have any open reservations, remaining tokens from the terminated campaign will be refunded to your account balance.The new state of the campaign will be "completed".
Open reservations expire 15 minutes after pausing a campaign.
Call:
campaign/terminate
Parameters:
INTEGER campaignId (required, the id of the campaign to be terminated)
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 305 | Campaign does not exist. |
| 306 | Only pending (paused) campaigns can be terminated, current status is $status. |
| 308 | This campaign still has $reservations reservations. After pausing a campaign, you may have to wait up to 15 minutes before a campaign can be completed. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("campaign/terminate", array('campaignId' => 286));
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[refundedTokens] => 49 // number of tokens refunded to the account
// [ floor (45 * 1.1) ]
)
4. Reporting Module
Summarized Statistics for the account
Summary:
Retrieves all statistics for the account for the given date range and filtered for an optional identifier.The returned data includes the number of currently running and active (pending, running, review) campaigns as well as impressions, clicks and transaction statistics for the specified date range. If identifier is set, only campaigns matching "identifier" are inspected.
Call:
reporting/summary
Parameters:
STRING startDate (required, the start date for the statistics retrieval)
STRING endDate (required, the end date for the statistics retrieval)
STRING identifier (optional, if set, only campaigns matching the identifier are inspected)
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 103 | Parameter out of range: Maximum date interval range is 365 days. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("reporting/summary", array( 'startDate' => '2014-01-25',
'endDate' => '2014-12-01',
'identifier' => 'customer1283'));
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[startDate] => 2014-01-25
[endDate] => 2014-12-01
[statistics] => Array
(
[activeCampaigns] => 70 // currently active campaigns
[runningCampaigns] => 51 // currently running campaigns
[impressions] => 8498599 // total impressions in the date range
[clicks] => 621865 // total clicks in the date range
[installs] => 349203 // total installs in the date range
[conversionRate] => 4 // conversion rate in percent, installs/clicks
)
)
Summarized Statistics for the account per day
Summary:
Retrieves all statistics for the account for the given date range and filtered for an optional identifier.The returned data includes the impressions, clicks and transaction statistics for the specified date range for each day. If identifier is set, only campaigns matching "identifier" are inspected.
Call:
reporting/summary_daily
Parameters:
STRING startDate (required, the start date for the statistics retrieval)
STRING endDate (required, the end date for the statistics retrieval)
STRING identifier (optional, if set, only campaigns matching the identifier are inspected)
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 106 | Parameter out of range: Maximum date interval range is 62 days. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("reporting/summary_daily", array( 'startDate' => '2015-01-25',
'endDate' => '2015-01-27',
'identifier' => 'customer1283'));
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[startDate] => 2015-01-25
[endDate] => 2015-01-27
[statistics] => Array
(
[2015-01-25] => Array
(
[impressions] => 129337 // total impressions this day
[clicks] => 14148 // total clicks this day
[installs] => 9159 // total installs this day
[conversionRate] => 7 // conversion rate in percent, installs/clicks
)
[2015-01-26] => Array
(
[impressions] => 76149
[clicks] => 7407
[installs] => 4591
[conversionRate] => 6
)
[2015-01-27] => Array
(
[impressions] => 97627
[clicks] => 11254
[installs] => 7099
[conversionRate] => 7
)
)
)
Installations for given campaign
Summary:
Retrieves all installations for the given campaign, timestamps are in UTC+0.Hint: For High Retention campaigns, only installation which successfully converted are listed.
Call:
reporting/installations
Parameters:
INTEGER campaignId (required, the id of the campaign to be returned)
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 305 | Campaign does not exist. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("reporting/installations", array('campaignId' => 287));
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[campaignData] => Array
(
[campaignId] => 287 // integer, unique id for this campaign
[identifier] => customer1 // string, the value supplied when creating the campaign
[packageName] => com.xxx.yyy // string, Play Store package name
[appName] => My Cool Calculator // string, English (US) title of the app
[appIcon] => https://lh5.ggpht.com/xx=w140 // string, URL to app icon
[targetCountries] => // string, country codes, empty for worldwide
[totalDownloads] => 50 // integer, total campaign volume
[remainingDownloads] => 0 // integer, remaining campaign volume
[reservations] => 0 // integer, users currently downloading app
[tokensPerDownload] => 1 // integer, price charged per install
[downloadRate] => 2400 // integer, maximum downloads per day
// 24-2400, 2400 means "unlimited"
[isRetention] => 0 // integer, 0 for standard campaigns, 1 for HR campaigns
[tracking] => standard // standard or custom_s2s (requires permissions)
[redirectUrl] => // empty for standard campaigns, the tracking url for s2s
[status] => completed // string, current campaign status
// pending, running, terminated
[created] => 2014-02-12 02:40:59 // string, creation date
)
[installations] => Array
(
[0] => Array
(
[timestamp] => 2014-02-12 15:19:49
[country] => DE
[identifier] => XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
[make] => Samsung
[model] => GT-I9300
)
[1] => Array
(
[timestamp] => 2014-02-12 15:21:15
[country] => CZ
[identifier] => XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
[make] => samsung
[model] => GT-P5100
)
......
)
)
Statistics for given campaign
Summary:
Retrieves all statistics for the given campaign.The returned data includes the campaign entry, a summary, detailed statistics (per day) and a list with country codes and their respective installation numbers.
Call:
reporting/stats
Parameters:
INTEGER campaignId (required, the id of the campaign to be returned)
Possible error codes:
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 305 | Campaign does not exist. |
| 429 | Too many consecutive API requests, throttled. |
Example:
$responseData = ayetRequest("reporting/stats", array('campaignId' => 287));
if ($responseData==null || !isset($responseData['status'])) {
// Network or server error
}
else if ($responseData['status']=="error") {
// API Call failed
echo "Error: ".$responseData['errorCode']." - '".$responseData['errorMessage']."'";
}
else {
print_r($responseData);
}
Example Output:
Array
(
[status] => success
[campaignData] => Array
(
[campaignId] => 287 // integer, unique id for this campaign
[identifier] => customer1 // string, the value supplied when creating the campaign
[packageName] => com.xxx.yyy // string, Play Store package name
[appName] => My Cool Calculator // string, English (US) title of the app
[appIcon] => https://lh5.ggpht.com/xx=w140 // string, URL to app icon
[targetCountries] => // string, country codes, empty for worldwide
[totalDownloads] => 50 // integer, total campaign volume
[remainingDownloads] => 0 // integer, remaining campaign volume
[reservations] => 0 // integer, users currently downloading app
[tokensPerDownload] => 1 // integer, price charged per install
[downloadRate] => 2400 // integer, maximum downloads per day
// 24-2400, 2400 means "unlimited"
[isRetention] => 0 // integer, 0 for standard campaigns, 1 for HR campaigns
[tracking] => standard // standard or custom_s2s (requires permissions)
[redirectUrl] => // empty for standard campaigns, the tracking url for s2s
[status] => completed // string, current campaign status
// pending, running, terminated
[created] => 2014-02-12 02:40:59 // string, creation date
)
[summary] => Array
(
[views] => 138
[clicks] => 72
[downloads] => 50
)
[detailed] => Array
(
[2014-02-12] => Array
(
[views] => 138
[clicks] => 72
[downloads] => 50
)
[2014-02-13] => Array
(
[views] => 0
[clicks] => 0
[downloads] => 0
)
)
[countries] => Array
(
[DE] => 4
[CZ] => 1
[IN] => 13
[DZ] => 2
[CA] => 2
[CO] => 1
[US] => 9
[GR] => 2
[IT] => 1
[AR] => 1
[ID] => 1
[ES] => 2
[PL] => 3
[GB] => 1
[TZ] => 1
[BG] => 1
[FR] => 1
[NO] => 1
[RU] => 1
[BY] => 1
[PH] => 1
)
)
Example Output:
Array
(
[status] => success
[campaignData] => Array
(
[campaignId] => 287 // integer, unique id for this campaign
[identifier] => customer1 // string, the value supplied when creating the campaign
[packageName] => com.xxx.yyy // string, Play Store package name
[appName] => My Cool Calculator // string, English (US) title of the app
[appIcon] => https://lh5.ggpht.com/xx=w140 // string, URL to app icon
[targetCountries] => // string, country codes, empty for worldwide
[totalDownloads] => 50 // integer, total campaign volume
[remainingDownloads] => 0 // integer, remaining campaign volume
[remainingRetentions] => 44 // integer, only available on HR campaigns
[reservations] => 0 // integer, users currently downloading app
[tokensPerDownload] => 1 // integer, price charged per install
[downloadRate] => 2400 // integer, maximum downloads per day
// 24-2400, 2400 means "unlimited"
[isRetention] => 1 // integer, 0 for standard campaigns, 1 for HR campaigns
[tracking] => standard // standard or custom_s2s (requires permissions)
[redirectUrl] => // empty for standard campaigns, the tracking url for s2s
[status] => running // string, current campaign status
// pending, running, terminated
[created] => 2014-02-12 02:40:59 // string, creation date
)
[summary] => Array
(
[views] => 147
[clicks] => 80
[downloads] => 55
[retentions] => 6 // HR only: shows the number of retentions for this campaign
[uninstalls] => 5 // HR only: shows the number of uninstalls for this campaign
)
[detailed] => Array
(
[2014-02-12] => Array
(
[views] => 138
[clicks] => 72
[downloads] => 50
[retentions] => 0 // HR only: shows the number of successful retentions
[uninstalls] => 4 // HR only: shows the number of uninstalls
)
[2014-02-13] => Array
(
[views] => 5
[clicks] => 5
[downloads] => 4
[retentions] => 0
[uninstalls] => 0
)
[2014-02-14] => Array
(
[views] => 0
[clicks] => 0
[downloads] => 0
[retentions] => 0
[uninstalls] => 1
)
[2014-02-15] => Array
(
[views] => 4
[clicks] => 2
[downloads] => 1
[retentions] => 6
[uninstalls] => 0
)
)
[countries] => Array
(
[DE] => 4
[CZ] => 1
[IN] => 13
[DZ] => 2
[CA] => 2
[CO] => 1
[US] => 14
[GR] => 2
[IT] => 1
[AR] => 1
[ID] => 1
[ES] => 2
[PL] => 3
[GB] => 1
[TZ] => 1
[BG] => 1
[FR] => 1
[NO] => 1
[RU] => 1
[BY] => 1
[PH] => 1
)
// retentionByDay shows how long users kept the app before uninstalling it
[retentionByDay] => Array
(
[0] => 4 // 4 users kept the app for less than 1 day
[1] => 0
[2] => 1
[3] => 0
[4] => 0
[5] => 0
[6] => 0
[7] => 0 // users who kept the app for 7+ days
)
// retentionByCountry shows how long users kept the app, segmented by country
[retentionByCountry] => Array
(
[US] => Array
(
[0] => 1 // 1 US user uninstalled on the first day
[1] => 0
[2] => 1 // 1 US user uninstalled after 2 days
[3] => 0
[4] => 0
[5] => 0
[6] => 0
[7] => 0
)
[IN] => Array
(
[0] => 3
[1] => 0
[2] => 0
[3] => 0
[4] => 0
[5] => 0
[6] => 0
[7] => 0
)
...
)
)
4. Appendix I: Error Codes
| errorCode | errorMessage |
| 100 | Authentification failed, check your API Key. |
| 101 | Unknown action "$action" for $module module. |
| 102 | Missing parameter: packageName. |
| 102 | Missing parameter: numDownloads. |
| 102 | Missing parameter: redirectUrl. |
| 103 | Parameter out of range: Maximum date interval range is 365 days. |
| 104 | Invalid parameter: tracking. |
| 105 | Invalid parameter: redirectUrl. |
| 106 | Parameter out of range: Maximum date interval range is 62 days. |
| 301 | Invalid countries requested: $invalidCountryCodes. |
| 302 | Minimum campaign volume is 20 downloads. |
| 302 | Maximum campaign volume is 10000 downloads. |
| 303 | Insufficient funds, $tokens available, $priceTokens required. |
| 304 | Selected app is not valid or not free. |
| 305 | Campaign does not exist. |
| 306 | Only pending campaigns can be started, current status is $status. |
| 306 | Only running campaigns can be paused, current status is $status. |
| 306 | Only pending (paused) campaigns can be terminated, current status is $status. |
| 308 | This campaign still has $reservations reservations. After pausing a campaign, you may have to wait up to 15 minutes before a campaign can be completed. |
| 310 | Insufficient account permissions to create custom s2s tracking campaigns. |
| 311 | Invalid redirect url. |
| 312 | Required parameter {click_id} missing in redirect url. |
| 313 | Custom s2s tracking is not supported for high retention campaigns. |
| 429 | Too many consecutive API requests, throttled. |