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

  1. Obtain API Key and Getting Started
  2. Account Module
  3. Campaign Module
  4. Reporting Module
  5. 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
305Campaign does not exist.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
301Invalid countries requested: $invalidCountryCodes.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
102Missing parameter: packageName.
102Missing parameter: numDownloads.
102Missing parameter: redirectUrl.
104Invalid parameter: tracking.
105Invalid parameter: redirectUrl.
301Invalid countries requested: $invalidCountryCodes.
302Minimum campaign volume is 20 downloads.
302Minimum campaign volume for retention campaigns is 50 downloads.
302Maximum campaign volume is 10000 downloads.
303Insufficient funds, $tokens available, $priceTokens required.
304Selected app is not valid or not free.
310Insufficient account permissions to create custom s2s tracking campaigns.
311Invalid redirect url.
312Required parameter {click_id} missing in redirect url.
313Custom s2s tracking is not supported for high retention campaigns.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
305Campaign does not exist.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
305Campaign does not exist.
306Only pending campaigns can be started, current status is $status.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
305Campaign does not exist.
306Only running campaigns can be paused, current status is $status.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
305Campaign does not exist.
306Only pending (paused) campaigns can be terminated, current status is $status.
308This campaign still has $reservations reservations. After pausing a campaign, you may have to wait up to 15 minutes before a campaign can be completed.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
103Parameter out of range: Maximum date interval range is 365 days.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
106Parameter out of range: Maximum date interval range is 62 days.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
305Campaign does not exist.
429Too 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:

errorCodeerrorMessage
100Authentification failed, check your API Key.
305Campaign does not exist.
429Too 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



errorCodeerrorMessage
100Authentification failed, check your API Key.
101Unknown action "$action" for $module module.
102Missing parameter: packageName.
102Missing parameter: numDownloads.
102Missing parameter: redirectUrl.
103Parameter out of range: Maximum date interval range is 365 days.
104Invalid parameter: tracking.
105Invalid parameter: redirectUrl.
106Parameter out of range: Maximum date interval range is 62 days.
301Invalid countries requested: $invalidCountryCodes.
302Minimum campaign volume is 20 downloads.
302Maximum campaign volume is 10000 downloads.
303Insufficient funds, $tokens available, $priceTokens required.
304Selected app is not valid or not free.
305Campaign does not exist.
306Only pending campaigns can be started, current status is $status.
306Only running campaigns can be paused, current status is $status.
306Only pending (paused) campaigns can be terminated, current status is $status.
308This campaign still has $reservations reservations. After pausing a campaign, you may have to wait up to 15 minutes before a campaign can be completed.
310Insufficient account permissions to create custom s2s tracking campaigns.
311Invalid redirect url.
312Required parameter {click_id} missing in redirect url.
313Custom s2s tracking is not supported for high retention campaigns.
429Too many consecutive API requests, throttled.