Exemplos em PHP

Visão geral

Todos os exemplos de código nesta seção usam as classes a seguir.

A classe Request usa cURL para fazer as solicitações à API.

A classe Response contém a resposta da API e informações do código de status retornado.

Classes Request e Response

class Request {

        /**
         * @var resource
         */
        protected $_request;

        /**
         * @var integer
         */
        protected $_method;

        /**
         * @var string
         */
        protected $_url;

        /**
         * @var array
         */
        protected $_headers = array(
            'Content-type: application/json'
        );

        /**
         * @var string|array
         */
        protected $_params;

        /**
         * @var object Response
         */
        protected $_reponse;

        /**
         * Construtor
         *
         * @param   string      $url
         * @param   string      $method
         * @param   array       $params
         */
        public function __construct($url, $method, $params = array()) {

            $this->_url = $url;

            // Definir o método
            $this->_method = $method;

            // Definir os parâmetros
            $this->_params = $params;
        }

        /**
         * Determinar o método da Request
         *
         * @param   string  $method
         */
        private function setMethod() {

            switch($this->_method) {
                case 'GET':
                    break;
                case 'POST':
                    curl_setopt($this->_request, CURLOPT_POST, 1);
                    break;
                case 'PUT':
                    curl_setopt($this->_request, CURLOPT_CUSTOMREQUEST, 'PUT');
                    break;
                case 'DELETE':
                    curl_setopt($this->_request, CURLOPT_CUSTOMREQUEST, 'DELETE');
                    break;
            }
        }

        /**
         * Adicionar cabeçalho de autorização
         *
         * @param   string  $type
         * @param   string  $token
         */
        public function setAuthorizationHeader($type, $token) {

            $authorization = $type . ' ' . $token;

            $this->_headers[] = 'Authorization: ' . $authorization;
        }

        /**
         * Adicionar corpo à solicitação
         */
        private function addBody() {

            if($this->_method != 'GET' && empty($this->_params) == false) {

                if(is_array($this->_params)) {
                    // Codificar o array em JSON
                    $this->_params = json_encode($this->_params);
                }

                curl_setopt($this->_request, CURLOPT_POSTFIELDS, $this->_params);

                // Adicionar um cabeçalho Content-length
                $this->_headers[] = 'Content-length: ' . strlen($this->_params);
            }
        }

        /**
         * Adicionar uma string de consulta à solicitação
         */
        private function addQueryString() {

            if($this->_method == 'GET' && is_array($this->_params) && count($this->_params) > 0) {

                $query_string = '?';

                foreach($this->_params as $param => $value) {

                    $query_string = $query_string . $param . '=' . $value . '&';
                }

                trim($query_string, '&');

                $this->_url = $this->_url . $query_string;
            }
            else {

                if(is_array($this->_params) && count($this->_params) > 0 && strpos($this->_url, '{') !== false) {
                    // Comparar parâmetros com a URL usando padrão
                    foreach($this->_params as $param => $value) {
                        $this->_url = preg_replace('/{' . $param . '}/', $value, $this->_url);
                    }
                }
            }
        }

        /**
         * Enviar a solicitação
         */
        public function send() {

            // Inicializar solicitação cURL
            $this->_request = curl_init();

            // Retornar a resposta como uma string
            curl_setopt($this->_request, CURLOPT_RETURNTRANSFER, 1);

            // Adicionar uma string de consulta
            $this->addQueryString();

            // Definir a URL
            curl_setopt($this->_request, CURLOPT_URL, $this->_url);

            // Definir o método da solicitação
            $this->setMethod();

            // Adicionar um corpo
            $this->addBody();

            if(empty($this->_headers) == false) {
                // Definir os cabeçalhos
                curl_setopt($this->_request, CURLOPT_HTTPHEADER, $this->_headers);
            }

            // Desativar verificações SSL
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYHOST, false);

            // Enviar a solicitação e armazenar o corpo
            $this->_response = new Response(curl_exec($this->_request));

            // Definir o código de status
            $this->_response->setStatusCode(curl_getinfo($this->_request, CURLINFO_HTTP_CODE));

            // Fechar a conexão
            curl_close($this->_request);
        }

        /**
         * Obter a resposta
         *
         * @return object
         */
        public function getResponse() {

            return $this->_response;
        }
    }

    class Response {

        /**
         * @var array
         */
        protected $_reason_phrases = array(
            //Informativo 1xx
            100 => "Continuar",
            101 => "Mudando de protocolo",

            // Sucesso 2xx
            200 => "OK",
            201 => "Criado",
            202 => "Aceito",
            203 => "Informação não autoritativa",
            204 => "Sem conteúdo",
            205 => "Redefinir conteúdo",
            206 => "Conteúdo parcial",

            // Redirecionamento 3xx
            300 => "Múltiplas escolhas",
            301 => "Movido permanentemente",
            302 => "Encontrado",
            303 => "Ver outro",
            304 => "Não modificado",
            305 => "Usar proxy",
            306 => "(Não utilizado)",
            307 => "Redirecionamento temporário",

            // Erro do cliente 4xx
            400 => "Pedido inválido",
            401 => "Não autorizado",
            402 => "Pagamento necessário",
            403 => "Proibido",
            404 => "Não encontrado",
            405 => "Método não permitido",
            406 => "Não aceitável",
            407 => "Autenticação de proxy necessária",
            408 => "Tempo limite da solicitação",
            409 => "Conflito",
            410 => "Indisponível",
            411 => "Comprimento necessário",
            412 => "Falha na pré-condição",
            413 => "Entidade da solicitação muito grande",
            414 => "URI da solicitação muito longa",
            415 => "Tipo de mídia não suportado",
            416 => "Intervalo solicitado não satisfatório",
            417 => "Falha na expectativa",

            // Erro do servidor 5xx
            500 => "Erro interno do servidor",
            501 => "Não implementado",
            502 => "Gateway inválido",
            503 => "Serviço indisponível",
            504 => "Tempo limite do gateway",
            505 => "Versão HTTP não suportada"
        );

        /**
         * @var integer
         */
        protected $_status_code;

        /**
         * @var string
         */
        protected $_body;

        /**
         * Construtor
         *
         * @param   string      $body
         */
        public function __construct($body) {

            $this->_body = $body;
        }

        /**
         * Construtor
         *
         * @param   string      $status_code
         */
        public function setStatusCode($status_code) {

            $this->_status_code = $status_code;
        }

        /**
         * Obter código de status
         *
         * @return  integer
         */
        public function getStatusCode() {

            return $this->_status_code;
        }

        /**
         * Obter corpo
         *
         * @return  string
         */
        public function getBody() {

            return $this->_body;
        }

        /**
         * Obter corpo decodificado em JSON
         *
         * @return  object|null
         */
        public function getBodyDecoded() {

            return json_decode($this->_body);
        }

        /**
         * Obter frase de motivo
         *
         * @return string|boolean
         */
        public function getReasonPhrase() {

            if(array_key_exists($this->_status_code, $this->_reason_phrases)) {

                return $this->_reason_phrases[$this->_status_code];
            }
            else {

                return false;
            }
        }
    }

Iniciar sessão

Há duas opções para solicitar a login rota:

• com nome de usuário e senha
• com token de API (token de acesso)

Exemplo de login com parâmetros de nome de usuário e senha.

<?php

    // Incluir as classes Request e Response

    $url = 'https://api.example.com/v2/login';

    $params = array(
        'username'  => 'sample_username',
        'password'  => 'sample_password'
    );

    // Criar um novo objeto Request
    $request = new Request($url, 'POST', $params);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Recuperar os detalhes do token de sessão
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody() . PHP_EOL;
    }
?>

Exemplo de login com token de API (token de acesso)

<?php

    // Incluir as classes Request e Response

    $url = 'https://api.example.com/v2/login';

    $params = array(
            'api_token'  => 'sample_token_2bb447abb71b69368901a....'
        );

    // Criar um novo objeto Request
    $request = new Request($url, 'POST', $params);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Recuperar os detalhes do token de sessão
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody() . PHP_EOL;
    }
?>

Autenticação

Cada solicitação a conteúdo relacionado ao usuário requer um Autorização cabeçalho a ser definido, com o valor contendo o tipo de token e o token de sessão recebido da solicitação de login da API.

Uma /login solicitação válida à API retornará o seguinte payload JSON.

{
  "token": "",
  "type": "",
  "expires_in": 0
}

O O token de sessão deve ser incluído em todas as solicitações subsequentes de conteúdo relacionado ao usuário para a API.

O type deve ser prefixado ao token, separado por um único espaço.

Bearer 4e63518d383d8fcaefb516fe708b893727463031

O expires_in é o tempo, em segundos, durante o qual o token será válido. Quando esse tempo expirar, será necessário obter um novo token por meio da solicitação /login.

Exemplo de obtenção e definição do cabeçalho de autorização com nome de usuário e senha

<?php

    // Incluir as classes Request e Response

    // Login
    $url = 'https://api.example.com/v2/login';

    $params = array(
        'username'  => 'sample_username',
        'password'  => 'sample_password'
    );

    // Criar um novo objeto Request
    $request = new Request($url, 'POST', $params);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Recuperar os detalhes do token de sessão
        $token = $response->getBodyDecoded();

        // Obter campanhas
        $url = 'https://api.example.com/v2/campaigns';

        // Criar um novo objeto Request
        $request = new Request($url, 'GET');

        // Definir o cabeçalho de autorização
        $request->setAuthorizationHeader($token->type, $token->token);

        // Enviar a solicitação
        $request->send();

        // Obter o objeto Response
        $response = $request->getResponse();

        if($response->getStatusCode() == 200) {

            // Recuperar as campanhas
            $campaigns = $response->getBodyDecoded();

            foreach($campaigns->result as $campaign) {
                // Exibir os nomes das campanhas
                echo $campaign->name . PHP_EOL;
            }
        }
        else {
            // Erro na solicitação de campanhas
            echo $response->getStatusCode() . PHP_EOL;
            echo $response->getReasonPhrase() . PHP_EOL;
            echo $response->getBody();
        }
    }
    else {
        // Login inválido
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Exemplo de obtenção e definição do cabeçalho de autorização com token de API

<?php

    // Incluir as classes Request e Response

    // Login
    $url = 'https://api.example.com/v2/login';

    $params = array(
        'api_token'  => 'sample_token_2bb447abb71b69368901a....'
    );

    ...

?>

Coleções

A seguir está um exemplo de uma solicitação para obter a Navegadores coleção.

<?php

    // Incluir as classes Request e Response

    $url = 'https://api.example.com/v2/collections/browsers';

    // Criar um novo objeto Request
    $request = new Request($url, 'GET');

    // Definir o cabeçalho de autorização recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $browsers = $response->getBodyDecoded();

        foreach($browsers as $browser) {

            echo $browser->id . ': ' . $browser->name . PHP_EOL;
        }
    }
    else {
        // Coleção não encontrada
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Estatísticas

A seguir está um exemplo de uma solicitação do anunciante para statistics/a/date.

No caso de additional_group_by o valor estar definido, a solicitação será agrupada pelo campo principal da rota e pelo(s) campo(s) extra(s).

Exemplo de estatísticas por data filtradas pelo ID da campanha 1234.

<?php

    // Incluir as classes Request e Response

    $url = 'https://api.example.com/v2/statistics/a/date';

    // Especificar o ID da campanha
    $params = array(
       'campaignid'  => 1234
    );

    $request = new Request($url, 'GET', $params);

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {

            echo $statistic->ddate . ': ' . $statistic->value . PHP_EOL;
        }
    }
    else {
        // Estatísticas da campanha não encontradas
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Exemplo de estatísticas por data com agrupamento adicional por campanha.

<?php

    // Incluir as classes Request e Response

    $url = 'https://api.example.com/v2/statistics/a/date';

    // Especificar o ID da campanha
    $params = array(
       'additional_group_by'  => 'campaign'
    );

    $request = new Request($url, 'GET', $params);

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo $statistic->ddate . ' - ' . $statistic->idcampaign . ': ' . $statistic->value . PHP_EOL;
        }
    }
    else {
        // Estatísticas da campanha não encontradas
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

post /statistics/a/global

Obter estatísticas globais do anunciante

Exemplo 1 de estatísticas globais

Exemplo de solicitação de estatísticas globais.

Apenas o group_by parâmetro é obrigatório. Os valores padrão dos outros parâmetros podem ser encontrados aqui.

Observe que as rotas de estatísticas globais (statistics/a/global, statistics/p/global) têm formatos de parâmetros diferentes.

<?php

    // Incluir as classes Request e Response

    $url = 'https://api.example.com/v2/statistics/a/global';

    // Especificar o group_by
    $params = [
        "group_by" => ["date"]
    ];

    $request = new Request($url, 'POST', $params);

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Data: ' . $statistic->group_by->date->date . ' -  Impressões: ' . $statistic->impressions .' - Custo: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Estatísticas da campanha não encontradas
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Exemplo 2 de estatísticas globais

Obter estatísticas por data, incluindo totais somados.

<?php

    // Incluir as classes Request e Response

    $url = 'https://api.example.com/v2/statistics/a/global';

    // Especificar o ID da campanha
    $params = [
        "filter" => [
            "date_from" => "2019-01-10",
            "date_to" => "2019-01-31",
        ],
        "totals" => 1,
        "group_by" => ["date"]
    ];

    $request = new Request($url, 'POST', $params);

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Data: ' . $statistic->group_by->date->date . ' -  Impressões: ' . $statistic->impressions .' - Custo: ' .  $statistic->cost . PHP_EOL;
        }

        echo 'Custo total:' . $statistics->result_total->cost . PHP_EOL;
    }
    else {
        // Estatísticas da campanha não encontradas
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Exemplo 3 de estatísticas globais

Obter estatísticas por campanha e país filtradas por data específica, ordenadas por impressões.

<?php

    // Incluir as classes Request e Response

    $url = 'https://api.example.com/v2/statistics/a/global';

    $params = [
        "filter" => [
            "date_from" => "2019-01-30",
            "date_to" => "2019-01-30",
        ],
        "group_by" => ["country_iso", "campaign_id"],
        "order_by" => [
            ["field" => "impressions", "order" => "desc"]
        ]
    ];


    $request = new Request($url, 'POST', $params);

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'País: ' . $statistic->group_by->country_iso->country_iso . ' -  ID da campanha: ' . $statistic->group_by->campaign_id->id .' - Custo: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Estatísticas da campanha não encontradas
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>

Exemplo 4 de estatísticas globais

Obter estatísticas do publisher por zona e país filtradas por sistema operacional específico.

<?php

    // Incluir as classes Request e Response

    $url = 'https://api.example.com/v2/statistics/p/global';

    $params = [
        "filter" => [
            "date_from" => "2019-01-30",
            "date_to" => "2019-01-30",
            "operating_system_id" => [11, 12]
        ],
        "group_by" => ["zone_id", "country_iso"]
    ];


    $request = new Request($url, 'POST', $params);

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo ' ID da zona:' . $statistic->group_by->zone_id->id . ' - País: ' . $statistic->group_by->country_iso->country_iso .' - Receita: ' .  $statistic->revenue . PHP_EOL;
        }
    }
    else {
        // Estatísticas da campanha não encontradas
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>