Diferencia entre revisiones de «Documentación API Analytics»
(→Link Tracking) |
(→Link Tracking) |
||
Línea 498: | Línea 498: | ||
</source> | </source> | ||
+ | =Resultado de las estadísticas= | ||
+ | Para que |
Revisión del 07:59 19 oct 2018
Contenido
Introduccion
La API Analytics es la plataforma a través de la cual obtener las estadísticas de un usuario. Los datos obtenidos corresponderán a los datos que se obtendrían en las secciones de Analytics del Panel de Mobeleader. Las estadísticas serán devueltas en formato JSON.
Para poder utilizar la API Analytics y poder obtener tanto el identificador de usuario como las claves RSA, deberá solicitarlo a su administrador.
En esta documentación se explicará cómo conectar con la API y cómo preparar los datos para realizar la petición de las estadísticas. Los ejemplos ofrecidos están en lenguaje PHP.
Conexión con la API
La conexión con la API para realizar la petición de estadísticas se puede realizar de dos maneras:
- Mediante llamada directa a la API. Esta opción será menos segura debido a que los datos de la petición irán sin cifrar.
- Usando la clase analyticsConnection creada por Mobeleader. Esta opción será mas segura ya que cuenta con un cifrado mediante RSA Keys generadas en nuestro sistema.
Llamada directa a la API
Si queremos realizar la petición a la API sin la necesidad de usar la clase analyticsConnection, deberemos conectarnos mediante POST a la siguiente URL: https://panel.mobeleader.com/webservices/analytics/api_analytics.php, añadiendo los parámetros data (JSON con los datos de la petición) y user (con el identificador del usuario). En el apartado Petición de estadísticas se explicará como obtener el identificador de usuario y como construir el JSON de la petición.
- Ejemplo de petición directa:
$url = 'https://panel.mobeleader.com/webservices/analytics/api_analytics.php';
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/x-www-form-urlencoded') );
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($curl, CURLOPT_POSTFIELDS, 'data='.urlencode($requestJson).'&user='.$useId);
$responseJson = curl_exec($curl);
Uso de la clase analyticsConnection
Esta clase accesible desde CAMBIARRRRR, esta pensada para una mayor comodidad del cliente, permitiendo que todo se gestione desde la clase sin necesidad de tener que programar las llamadas y retornos de la API. A continuación se expondrán los pasos a seguir para un correcto funcionamiento de la clase:
Instalación PHPSECLIB
Será necesario disponer de phpseclib versión 2.0.11 o superior.
Los pasos para instalar esta versión de phpseclib son:
- Disponer de la herramienta "composer.phar"
- Ejecutar "composer" en la carpeta donde vaya a instalar nuestra librería.
1.- Descargar composer desde: https://getcomposer.org/composer.phar
curl https://getcomposer.org/composer.phar -o composer.phar
2.- Ejecutar el comando:
php composer.phar --working-dir=. require phpseclib/phpseclib:~2.0
Hecho esto, obtendrá la siguiente salida por consola:
./composer.json has been created Loading composer repositories with package information Updating dependencies (including require-dev) Package operations: 1 install, 0 updates, 0 removals - Installing phpseclib/phpseclib (2.0.11): Downloading (100%) phpseclib/phpseclib suggests installing ext-libsodium (SSH2/SFTP can make use of some algorithms provided by the libsodium-php extension.) phpseclib/phpseclib suggests installing ext-mcrypt (Install the Mcrypt extension in order to speed up a few other cryptographic operations.) phpseclib/phpseclib suggests installing ext-gmp (Install the GMP (GNU Multiple Precision) extension in order to speed up arbitrary precision integer arithmetic operations.) Writing lock file Generating autoload files
Esto significa que está todo lo necesario instalado en su carpeta vendor.
Clase analyticsConnection
Una vez instalada la librería PHPSECLIB en nuestra carpeta vendor, lo primero que debemos hacer es abrir la clase y modificar la ruta de acceso a dicha carpeta.
require_once 'PATH..../vendor/autoload.php';
Tras modificar la ruta, para poder instanciar la clase obtendremos la RSA KEY Privada, accesible desde la sección Mis Datos del Panel de Mobeleader.
Pulsando en Ver claves RSA abriremos un popup en el que podremos obtener las claves RSA.
Copiaremos la cadena perteneciente al campo Private RSA key. Es necesario copiar la cadena completa, incluyendo -----BEGIN RSA PRIVATE KEY----- y -----END RSA PRIVATE KEY-----. Añadiremos la cadena como parámetro (string) del constructor de la clase analyticsConnection tal y como se muestra en el ejemplo siguiente:
$apiconnection = new analyticsConnection([RSA_PRIVATE_KEY]);
Una vez realizadas correctamente la instalación de la librería, la modificación de la ruta de acceso a ésta, y la inserción en el código de la RSA KEY Privada, para realizar las llamadas a la API usaremos la función getData() de la clase analyticsConnection, añadiendo el JSON con los datos de la petición y el identificador del usuario. La función getData() será la encargada de realizar todas las conexiones a la API, de cifrar los datos que enviaremos a ésta y de descifrar los datos que nos devuelva.
$apiconnection = new analyticsConnection([RSA_PRIVATE_KEY]);
$responseJson = $apiconnection->getData($userId, $requestJson)
En el apartado Petición de estadísticas se explicará cómo obtener el identificador de usuario y cómo construir el JSON de la petición
Petición de estadísticas
Para que la petición de estadísticas se realice correctamente, es necesario enviar, dentro de la petición, su identificador de usuario y un JSON en el cual especificar las estadísticas que quiera obtener (campos de las estadísticas, filtros, fechas, etc.).
Las peticiones a la API son limitadas. Una vez recibida la respuesta de estadísticas (a excepción de haber devuelto un error), deberá esperar un minuto para hacer la siguiente consulta.
Identificador de usuario
Para realizar la petición de estadísticas a la API Analytics, lo primero que debe hacer es obtener el identificador de usuario. Para ello diríjase a la sección Mis Datos del Panel de Mobeleader y pulse en Ver claves RSA. Una vez dentro del popup, copie la cadena perteneciente al campo Public Identifier.
JSON de petición de estadísticas
Para obtener las estadísticas deseadas, es necesario crear un JSON en el que se especifique:
- El tipo de petición, especificado en el campo type: minería, desarrollo, etc.
- Los elementos de los cuales quiera obtener las estadísticas, especificados en el campo require: por anuncio, por app, por sistema operativo, etc.
- Las estadísticas que quiera mostrar, especificadas en el campo fields: impresiones, descargas, hashes minados, etc.
- Los filtros o elementos concretos de los que quiera obtener las estadísticas, especificados en el campo filters: determinadas apps, bases de datos, etc.
- Las fechas entre las que quiera delimitar la petición, especificadas en el campo dates.
Tipos
Cada tipo de petición devolverá un tipo de estadísticas, en función del tipo de usuario que realice la petición, así como los permisos que le hayan sido otorgados. El tipo de petición se especificará en el campo type del JSON. Los diferentes valores para el tipo de petición son:
- mailing: Devuelve las estadísticas de los envíos de Mailing. El usuario ha de tener acceso a las secciones de Mailing en el Panel de Mobeleader.
- marketing: Devuelve las estadísticas de los anuncios. El usuario ha de tener acceso a las secciones de Agencias en el Panel de Mobeleader.
- miner: Devuelve las estadísticas minería. El usuario ha de tener acceso a las secciones de Minería en el Panel de Mobeleader.
- developer: Devuelve las estadísticas de las aplicaciones. El usuario ha de tener acceso a las secciones de Desarrolladores en el Panel de Mobeleader.
- linkTracking: Devuelve las estadísticas de descargas por URL tracking. El usuario ha de tener acceso a las sección Link Management en el Panel de Mobeleader.
Mailing
- El campo require es obligatorio, e indica el tipo de elemento del que se quiere obtener las estadísticas:
- db: Devolverá las estadísticas por Base de datos.
- mail: Devolverá las estadísticas por envío.
- campaign: Devolverá las estadísticas por campaña.
- domain: Devolverá las estadísticas por dominio.
- sender: Devolverá las estadísticas por sender (enviador).
- emailAdress: Devolverá las estadísticas por dirección de email desde la que se hayan realizado los envíos.
- country: Devolverá las estadísticas por país.
- El campo fields es obligatorio, e indica qué valores de las estadísticas se quieren obtener. Los valores del campo fields irán especificados dentro de un array y podrán ser los siguientes:
- sent: emails enviados.
- views: impresiones totales obtenidas.
- unique_views: impresiones únicas.
- clicks: clicks totales realizados.
- unique_clicks: clicks únicos.
- leads: registros totales realizados.
- unique_leads: registros únicos.
- unsubscribes: bajas ejecutadas.
- soft_bounces: soft bonces devueltos.
- hard_bounces: hard bonces devueltos.
- or: tasa de aperturas.
- cr: tasa de clicks.
- ur: tasa de bajas.
- br: tasa de bonces o rebotados.
- rr: tasa de reactividad.
- dr: tasa de entregabilidad.
- El campo filters es opcional, e indica los elementos concretos de los que se quieren obtener las estadísticas. Los valores del campo filters irán especificados dentro de un array y corresponderán al identificador de cada elemento dentro del Panel de Mobeleader. Podrán ser los siguientes:
- senders: Array que especifica los senders o enviadores de los que se quieren obtener las estadísticas. Puede añadir los identificadores 'MailingCP' y 'AmazonSES'.
- dataBases: Array que especifica las bases de datos de las que se quieren obtener las estadísticas. Los identificadores de sus bases de datos los podrá obtener en la columna Id correspondiente a cada base de datos en la sección BBDD del Panel de Mobeleader.
- campaigns: Array que especifica las campañas de las que se quieren obtener las estadísticas. Los identificadores de sus campañas los podrá obtener en la columna Id correspondiente a cada campaña en la sección Campañas del Panel de Mobeleader.
- domains: Array que especifica los dominios de los que se quieren obtener las estadísticas. Los identificadores de sus dominios los podrá obtener en la columna Id correspondiente a cada dominio en la sección Dominios del Panel de Mobeleader.
- campaignType: Valor que especifica el tipo de campaña de la que se quiere obtener las estadísticas. Puede elegir entre uno de los siguientes tipos:
- transactional: Para envíos transaccionales.
- autoresponder: Para envíos automáticos.
- newsletter: Para envíos boletín.
- transactional: Para envíos de marketing.
- emails: Array que especifica las direcciones de email de las que se quieren obtener las estadísticas. Para obtener los identificadores de sus direcciones de email deberá dirigirse a la sección Dominios del Panel de Mobeleader. Una vez ahí, pulse en el icono Ver emails en la columna Emails. Dentro del popup en el que se muestran las direcciones de email del dominio seleccionado, podrá obtener el identificador en la columna Id correspondiente a cada dirección de email.
- mailings: Array que especifica los envíos de los que se quieren obtener las estadísticas. Los identificadores de sus envíos los podrá obtener en la columna Id correspondiente a cada envío en la sección Envíos Transaccionales para los envíos transaccionales, en la sección Envíos Auto-Responder para los envíos autoresponder, en la sección Envíos Boletín para los envíos boletín y en la sección Envíos Marketing para los envíos de marketing del Panel de Mobeleader.
- El campo dates es opcional, e indica las fechas entre las cuales queremos obtener las estadísticas. Los valores del campo dates irán especificados dentro de un array, en formato 'YYYY-MM-DD' y podrán ser los siguientes:
- firstDate: fecha de inicio.
- lastDate: fecha de fin.
- Ejemplo de petición de estadísticas por campaña con todos los campos y los filtros:
{
"type":"mailing",
"require":"campaign",
"fields":["sent","views","unique_views","clicks","unique_clicks","leads","unique_leads","unsubscribes","soft_bounces","hard_bounces","or","cr","ur","br","rr","dr"],
"filters":{
"senders":["MailingCP"],
"dataBases":[1,3,4],
"campaigns":[221,302,357],
"campaignType":"newsletter",
"domains":[3,25,27],
"emails":[59,162],
"mailings":[324,17835]
},
"dates":{
"firstDate":"2018-09-01",
"lastDate":"2018-09-02"
}
}
- Ejemplo de petición de estadísticas por envío con algunos de los campos y filtros:
{
"type":"mailing",
"require":"mail",
"fields":["sent","views","clicks","leads","unsubscribes"],
"filters":{
"dataBases":[1,3,4],
"campaigns":[221,302,357],
"campaignType":"marketing",
"emails":[59,162],
"mailings":[17835]
},
"dates":{
"firstDate":"2018-09-01"
}
}
Marketing
- El campo require es obligatorio, e indica los elementos de los que se quiere obtener las estadísticas. Los valores del campo require irán especificados dentro de un array y podrán combinarse. Los valore son los siguientes:
- ad: Devolverá las estadísticas por Anuncio o Campaña.
- domain: Devolverá las estadísticas por Web.
- creativity: Devolverá las estadísticas por Creatividad.
- date: Devolverá las estadísticas por fecha.
- El campo fields es obligatorio, e indica qué valores de las estadísticas se quieren obtener. Los valores del campo fields irán especificados dentro de un array y podrán ser los siguientes:
- clicks: clicks totales realizados.
- unique_clicks: clicks únicos.
- ctr: CTR.
- validated_leads: registros validados.
- pending_leads: registros pendientes.
- total_leads: registros totales.
- rejected_leads: registros rechazados.
- validated_expenditures: gastos validados.
- pending_expenditures: gastos pendientes.
- total_expenditures: gastos totales.
- validated_profits: beneficios validados.
- pending_profits: beneficios pendientes.
- total_profits: beneficios totales.
- El campo filters es opcional, e indica los elementos concretos de los que se quiere obtener las estadísticas. Los valores del campo filters irán especificados dentro de un array y corresponderán al identificador de cada elemento dentro del Panel de Mobeleader. Podrán ser los siguientes:
- campaigns: Array que especifica los anuncios o campañas de las que se quiere obtener las estadísticas. Los identificadores de sus campañas los podrá obtener en la columna Id correspondiente a cada campaña en la sección Mis Anuncios del Panel de Mobeleader.
- domains: Array que especifica las webs de las que se quiere obtener las estadísticas. Los identificadores de sus webs los podrá obtener en la columna Id correspondiente a cada web en la sección Mis Webs del Panel de Mobeleader.
- creativities: Array que especifica las creatividades de las que se quiere obtener las estadísticas. Los identificadores de sus creatividades los podrá obtener en la columna Id correspondiente a cada creatividad en la sección Mis Creatividades del Panel de Mobeleader.
- El campo dates es opcional, e indica las fechas entre las cuales queremos obtener las estadísticas. Los valores del campo dates irán especificados dentro de un array, en formato 'YYYY-MM-DD' y podrán ser los siguientes:
- firstDate: fecha de inicio.
- lastDate: fecha de fin.
- Ejemplo de petición de estadísticas con todos los campos y los filtros:
{
"type":"marketing",
"require":["ad","domain","creativity","date"],
"fields":["clicks","unique_clicks","ctr","validated_leads","pending_leads","total_leads","rejected_leads","validated_expenditures","pending_expenditures","total_expenditures","validated_profits","pending_profits","total_profits"],
"filters":{
"campaigns":[3,125,408],
"domains":[95,512],
"creativities":[27,135]
},
"dates":{
"firstDate":"2018-09-03",
"lastDate":"2018-09-11"
}
}
- Ejemplo de petición de estadísticas por campaña y web, con algunos de los campos y filtros:
{
"type":"marketing",
"require":["ad","domain"],
"fields":["clicks","unique_clicks","total_leads","total_expenditures","total_profits"],
"filters":{
"campaigns":[3],"domains":[95,512]
},
"dates":{
"firstDate":"2018-09-03"
}
}
Miner
- El campo require es obligatorio, e indica los elementos de los que se quiere obtener las estadísticas. Los valores del campo require irán especificados dentro de un array y podrán combinarse. Los valore son los siguientes:
- worker: Devolverá las estadísticas por worker.
- wallet: Devolverá las estadísticas por wallet.
- workerType: Devolverá las estadísticas por tipo de worker (app, web, link, etc).
- coin: Devolverá las estadísticas por divisa.
- date: Devolverá las estadísticas por fecha.
- El campo fields es obligatorio, e indica qué valores de las estadísticas se quieren obtener. Los valores del campo fields irán especificados dentro de un array y podrán ser los siguientes:
- payout: pago estimado.
- hashes: hashes minados.
- shares: hashes validados.
- hashrate: hashes por segundo.
- El campo filters es opcional, e indica los elementos concretos de los que se quiere obtener las estadísticas. Los valores del campo filters irán especificados dentro de un array y corresponderán al identificador de cada elemento dentro del Panel de Mobeleader. Podrán ser los siguientes:
- workers: Array que especifica los workers de los que se quiere obtener las estadísticas. Los identificadores de sus workers los podrá obtener en la columna Id correspondiente a cada workers en la sección Mis Workers del Panel de Mobeleader.
- wallets: Array que especifica los wallets de los que se quiere obtener las estadísticas. Los identificadores de sus wallets los podrá obtener en la columna Id correspondiente a cada wallet en la sección Mis Wallets del Panel de Mobeleader.
- coins: Array que especifica las divisas de las que se quiere obtener las estadísticas. Puede añadir las siguientes divisas:
- bcn: Bytecoin.
- xmr: Monero.
- workerTypes: Array que especifica los diferentes tipos de workers de los que se quiere obtener las estadísticas. Puede añadir los siguientes tipos:
- app: aplicación.
- web: web.
- wallet: wallet.
- link: link de redireccionamiento.
- captcha: captcha de validación.
- El campo dates es opcional, e indica las fechas entre las cuales queremos obtener las estadísticas. Los valores del campo dates irán especificados dentro de un array, en formato 'YYYY-MM-DD' y podrán ser los siguientes:
- firstDate: fecha de inicio.
- lastDate: fecha de fin.
- Ejemplo de petición de estadísticas con todos los campos y los filtros:
{
"type":"miner",
"require":["worker","wallet","coin","workerType","date"],
"fields":["payout","hashes","shares","hashrate"],
"filters":{
"workers":[39,62],
"wallets":[1,5,6],
"workerTypes":["app","web","wallet","link","captcha"],
"coins":["bcn","xmr"]
},
"dates":{
"firstDate":"2018-09-01",
"lastDate":"2018-09-30"
}
}
- Ejemplo de petición de estadísticas por worker y wallet, con algunos de los campos y filtros:
{
"type":"miner",
"require":["worker","wallet"],
"fields":["hashes","hashrate"],
"filters":{
"workers":[39,62],
"workerTypes":["app","web"],
"coins":["xmr"]
}
}
Developer
- El campo require es obligatorio, e indica el tipo de elemento del que se quiere obtener las estadísticas:
- app: Devolverá las estadísticas por aplicación.
- place: Devolverá las estadísticas por espacio.
- os: Devolverá las estadísticas por sistema operativo.
- osVersion: Devolverá las estadísticas por versión del sistema operativo.
- brand: Devolverá las estadísticas por marca del terminal.
- country: Devolverá las estadísticas por país.
- El campo fields es obligatorio, e indica qué valores de las estadísticas se quieren obtener. Los valores del campo fields irán especificados dentro de un array y podrán ser los siguientes:
- views: impresiones obtenidas.
- clicks: clicks realizados.
- downloads: descargas obtenidas.
- El campo filters es opcional, e indica los elementos concretos de los que se quieren obtener las estadísticas. Los valores del campo filters irán especificados dentro de un array y corresponderán al identificador de cada elemento dentro del Panel de Mobeleader. Podrán ser los siguientes:
- oss: Array que especifica los sistemas operativos de los que se quiere obtener las estadísticas. Puede añadir los identificadores 'android' e 'ios'.
- apps: Array que especifica las aplicaciones de las que se quiere obtener las estadísticas. Los identificadores de sus aplicaciones los podrá obtener en la columna Id correspondiente a cada aplicación en la sección Mis Aplicaciones del Panel de Mobeleader.
- places: Array que especifica los espacios de los que se quiere obtener las estadísticas. Los identificadores de sus espacios los podrá obtener en la columna Id correspondiente a cada espacio en la sección Mis Espacios del Panel de Mobeleader.
- El campo dates es opcional, e indica las fechas entre las cuales queremos obtener las estadísticas. Los valores del campo dates irán especificados dentro de un array, en formato 'YYYY-MM-DD' y podrán ser los siguientes:
- firstDate: fecha de inicio.
- lastDate: fecha de fin.
- Ejemplo de petición de estadísticas por aplicación con todos los campos y los filtros:
{
"type":"developer",
"require":"app",
"fields":["views","clicks","downloads"],
"filters":{
"oss":"android",
"apps":[13,63],
"places":[85,125,198]
},
"dates":{
"firstDate":"2018-09-01",
"lastDate":"2018-09-07"
}
}
- Ejemplo de petición de estadísticas por país con algunos de los campos y filtros:
{
"type":"developer",
"require":"country",
"fields":["views","clicks"],
"filters":{
"apps":[63],
"places":[85,125,198]
},
"dates":{
"lastDate":"2018-09-07"
}
}
Link Tracking
- El campo require es obligatorio, e indica los elementos de los que se quiere obtener las estadísticas. Los valores del campo require irán especificados dentro de un array y podrán combinarse. No puede combinarse el campo link con los campos field y value, por lo que si decide incluir el campo link no se mostrarán las estadísticas por field y value. Los valore son los siguientes:
- app: Devolverá las estadísticas por aplicación.
- os: Devolverá las estadísticas por sistema operativo.
- date: Devolverá las estadísticas por fecha.
- link: Devolverá las estadísticas por link.
- field: Devolverá las estadísticas por campo.
- value: Devolverá las estadísticas por valor.
- El campo filters es opcional, e indica los elementos concretos de los que se quiere obtener las estadísticas. Los valores del campo filters irán especificados dentro de un array y corresponderán al identificador de cada elemento dentro del Panel de Mobeleader. Podrán ser los siguientes:
- apps: Array que especifica las aplicaciones de las que se quiere obtener las estadísticas. Los identificadores de sus aplicaciones los podrá obtener en la columna Id correspondiente a cada aplicación en la sección Mis Aplicaciones del Panel de Mobeleader.
- links: Array que especifica los links de los que se quiere obtener las estadísticas. Los identificadores de sus links los podrá obtener en la columna Id correspondiente a cada link en la sección Link Management del Panel de Mobeleader.
- os: Array que especifica los sistemas operativos de los que se quiere obtener las estadísticas. Puede añadir los identificadores 'android' e 'ios'.
- fields: Array que especifica los campos de los que se quiere obtener las estadísticas. Los nombres de cada campo los podrá obtener en el recuadro Campos opcionales correspondiente a cada link (en caso de haber sido configurados) en la sección Link Management del Panel de Mobeleader.
- values: Array que especifica los valores de los campos de los que se quiere obtener las estadísticas. Los valores de cada campo los podrá obtener en el recuadro Campos opcionales correspondiente a cada link (en caso de haber sido configurados) en la sección Link Management del Panel de Mobeleader.
- El campo dates es opcional, e indica las fechas entre las cuales queremos obtener las estadísticas. Los valores del campo dates irán especificados dentro de un array, en formato 'YYYY-MM-DD' y podrán ser los siguientes:
- firstDate: fecha de inicio.
- lastDate: fecha de fin.
- Ejemplo de petición de estadísticas por aplicación, sistema operativo,campo, valor y fecha, con todos los filtros:
{
"type":"linkTracking",
"require":["app","os","field","value","date"],
"filters":{
"apps":[13,63],
"links":[2,10],
"os":"android",
"fields":["campo1","campo2"],
"values":["valor1","valor2"]
},
"dates":{
"firstDate":"2018-10-01",
"lastDate":"2018-10-12"
}
}
- Ejemplo de petición de estadísticas por aplicación y link, con algunos de los campos y filtros:
{
"type":"linkTracking",
"require":["app","link"],
"filters":{
"apps":[13,63],
"links":[2,10],
"values":["valor1"]
},
"dates":{
"lastDate":"2018-10-12"
}
}
Resultado de las estadísticas
Para que