Saltar a: navegación, buscar

Documentación Webservice NickCenter

Revisión del 10:24 7 jun 2019 de Deneb (discusión | contribuciones) (→‎Clase spsApiConnection)

Introduccion

En ésta documentación se expondrá como deberemos hacer uso del Webservice de NickCenter, de manera que emule la propia librería de NickCenter y así no haya la necesidad de usarla ni implementarla en las aplicaciones. A pesar de ello, la configuración en el panel de Mobeleader será la misma, siendo necesario dar de alta la aplicación en éste, y configurandola para el uso de NickCenter. Podremos hacer uso de dicho Webservice de dos maneras:

  1. Llamada directa al Webservice. Ésta opción será menos segura debido a que los datos irán sin cifrar.
  2. Usando la clase spsApiNickcenter creada por Mobeleader. Esta opción será mas segura ya que cuenta con un cifrado mediante RSA Keys generadas en nuestro sistema.

Conexión con el Webservice

La conexión con el Webservice se puede realizar de dos maneras:

  1. Mediante llamada directa al Webservice. Esta opción será menos segura debido a que los datos de la petición irán sin cifrar.
  2. Usando la clase spsApiConnection creada por Mobeleader. Esta opción será mas segura ya que cuenta con un cifrado mediante claves RSA generadas en nuestro sistema.

Llamada directa

Si queremos usar directamente el Webservice de Nickcenter sin la necesidad de usar la clase analyticsConnection, esta será la URL a la que deberemos conectarnos mediante POST https://nickcenter.mobeleader.com/webservice_nickcenter.php?data=. Más adelante se expondrán que tareas hay disponibles y como hay que mandar los datos para su ejecución.

  • Ejemplo de petición directa con task (tarea) checkActive, una app concreta (añadiendo el hash que le correspondiera) y country (país) ES (España):
$url = 'https://nickcenter.mobeleader.com/webservice_nickcenter.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('task=checkActive&app=my_app_hash&country=ES'));
$responseJson = curl_exec($curl);

Uso de la clase spsApiConnection

La clase spsApiConnection, 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. Puede descargar el archivo desde aquí. A continuación se exponen 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. Para instalar esta versión de phpseclib deberá:
- 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 spsApiConnection

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';


Una vez modificada la ruta, para poder instanciar la clase deberemos coger la cadena de la RSA KEY Privada, accesible desde nuestro panel, y reemplazarla en el siguiente codigo. 

require_once "PATH..../api_connection_class.php";
$conexionapi = new spsApiConnection([RSA KEY PRIVADA]);


Si la instalación de la librería es correcta, la ruta de acceso a ésta ha sido cambiada y es correcta, y la RSA KEY Privada es correcta, para realizar las llamadas al Webservice usaremos la funcion getWebserviceData() de la clase spsApiConnection. Dicha función será la encargada de realizar todas las conexiones al Webservice, de cifrar los datos que enviaremos a éste y de descifrar los que datos que nos retorne. 

require_once "PATH..../api_connection_class.php";
$conexionapi = new spsApiConnection([RSA KEY PRIVADA]);
$json_datos_devueltos = $conexionapi->getWebserviceData(tarea, array_datos)


A continuación se exponen cuales son las distintas tareas ejecutables, y como ha de ser el array de datos para posibilitar dicha ejecución.

Tareas

La clase spsApiConnection consta de la función getData(tarea, array_datos), con la que ejecutaremos las distintas operaciones que el Webservice permite y a la que le deberemos mandar los siguientes parámetros:

  1. tarea: Sera la propia tarea a realizar, puediendo ser:
    1. checkActive.
    2. requestFields.
    3. register.
    4. update.
    5. login.
    6. rescuePassword.
  2. array_datos: Contendrá un array con los datos necesarios para la ejecución de la tarea.

Llamadas al Webservice

Recuerde reemplazar el contenido de los ejemplos por los valores reales.

  • checkActive: Esta tarea comprobará que la aplicación tenga NickCenter activo, independientemente de usarla directamente o no, el resto de tareas harán uso de ella antes de realizar sus operaciones propias.
  • app: Contendrá el hash de la aplicación dada de alta en el panel de Mobeleader.
  • country: Contendrá el país del dispositivo, necesario para comprobar si NickCenter esta activo para esa aplicación en ese país.
  • Ejemplo llamada directa: 
https://nickcenter.mobeleader.com/webservice_nickcenter.php?data=task=checkActive&app=[hash aplicacion, ej: 1234567890ABCDEF]&country=[código país, ej: ES]
  • Ejemplo spsApiNickcenter:
$array_datos = array();
$array_datos['app'] = [hash aplicacion, ej: 1234567890ABCDEF];
$array_datos['country'] = [código país, ej: ES];

$conexionapi = new spsApiNickcenter([RSA KEY PRIVADA asociada a su aplicación]);
$json_datos_devueltos = $conexionapi->getData('checkActive', $array_datos);


  • requestFields: Mediante ésta tarea obtendremos la configuración de campos y traducciones para una determinada vista.
    • app: Contendrá el hash de la aplicación dada de alta en el panel de Mobeleader.
    • view: Indicará los campos de que vista solicitamos.
      • register: Pantalla inicial del registro.
      • login: Pantalla de login.
      • rescue: Pantalla de recuperación de contraseña.
    • country: Contendrá el país del dispositivo, necesario para comprobar si NickCenter esta activo para esa aplicación en ese país.
    • language: Idioma del dispositivo, necesario para las traducciones y las configuraciones de los campos que se retornarán.
  • Ejemplo llamada directa: 
https://nickcenter.mobeleader.com/webservice_nickcenter.php?data=task=requestFields&app=[hash aplicacion, ej: 1234567890ABCDEF]&view=[vista, ej: register]&country=[código país, ej: ES]&language=[código idioma, ej: es]
  • Ejemplo spsApiNickcenter:
$array_datos = array();
$array_datos['app'] = [hash aplicacion, ej: 1234567890ABCDEF];
$array_datos['view'] = [vista, ej: register];
$array_datos['country'] = [código país, ej: ES];
$array_datos['language'] = [código idioma, ej: es];

$conexionapi = new spsApiNickcenter([RSA KEY PRIVADA asociada a su aplicación]);
$json_datos_devueltos = $conexionapi->getData('requestFields', $array_datos);


  • register: Esta tarea servirá para registrar un usuario en nuestro sistema.
    • app: Contendrá el hash de la aplicación dada de alta en el panel de Mobeleader.
    • jsonDevice: Contendrá los datos del dispositivo. Más adelante se exponen que campos son obligatorios.
    • jsonApp: Contendrá los datos de la aplicación. Más adelante se exponen que campos son obligatorios.
    • jsonUser: Contendrá los datos del usuario. Más adelante se exponen que campos son obligatorios.
  • Ejemplo llamada directa: 
https://nickcenter.mobeleader.com/webservice_nickcenter.php?data=task=register&app=[hash aplicacion, ej: 1234567890ABCDEF]&jsonDevice=[json con toda la información del dispositivo]&jsonApp=[json con toda la información de la app]&jsonUser=[json con toda la información a registrar del usuario]
  • Ejemplo spsApiNickcenter:
$array_datos = array();
$array_datos['app'] = [hash aplicacion, ej: 1234567890ABCDEF];
$array_datos['jsonDevice'] = [json con toda la información del dispositivo];
$array_datos['jsonApp'] = [json con toda la información de la app];
$array_datos['jsonUser'] = [json con toda la información a registrar del usuario];

$conexionapi = new spsApiNickcenter([RSA KEY PRIVADA asociada a su aplicación]);
$json_datos_devueltos = $conexionapi->getData('register', $array_datos);


  • update: Esta tarea servirá para actualizar un usuario que previamente haya sido registrado en nuestro sistema.
    • app: Contendrá el hash de la aplicación dada de alta en el panel de Mobeleader.
    • jsonDevice: Contendrá los datos del dispositivo. Más adelante se exponen que campos son obligatorios.
    • jsonApp: Contendrá los datos de la aplicación. Más adelante se exponen que campos son obligatorios.
    • jsonUser: Contendrá los datos del usuario. Más adelante se exponen que campos son obligatorios.
  • Ejemplo llamada directa: 
https://nickcenter.mobeleader.com/webservice_nickcenter.php?data=task=update&app=[hash aplicacion, ej: 1234567890ABCDEF]&jsonDevice=[json con toda la información del dispositivo]&jsonApp=[json con toda la información de la app]&jsonUser=[json con toda la información a actualizar del usuario]
  • Ejemplo spsApiNickcenter:
$array_datos = array();
$array_datos['app'] = [hash aplicacion, ej: 1234567890ABCDEF];
$array_datos['jsonDevice'] = [json con toda la información del dispositivo];
$array_datos['jsonApp'] = [json con toda la información de la app];
$array_datos['jsonUser'] = [json con toda la información a actualizar del usuario];

$conexionapi = new spsApiNickcenter([RSA KEY PRIVADA asociada a su aplicación]);
$json_datos_devueltos = $conexionapi->getData('update', $array_datos);


  • login: Esta tarea servirá para hacer login en las aplicaciones registradas en NickCenter, con usuarios previamente registrados en nuestro sistema.
    • app: Contendrá el hash de la aplicación dada de alta el panel de en Mobeleader.
    • jsonDevice: Contendrá los datos del dispositivo. Más adelante se exponen que campos son obligatorios.
    • jsonApp: Contendrá los datos de la aplicación. Más adelante se exponen que campos son obligatorios.
    • jsonUser: Contendrá los datos del usuario. Más adelante se exponen que campos son obligatorios.
  • Ejemplo llamada directa: 
https://nickcenter.mobeleader.com/webservice_nickcenter.php?data=task=login&app=[hash aplicacion, ej: 1234567890ABCDEF]&jsonDevice=[json con toda la información del dispositivo]&jsonApp=[json con toda la información de la app]&jsonUser=[json con toda la información necesaria para el login]
  • Ejemplo spsApiNickcenter:
$array_datos = array();
$array_datos['app'] = [hash aplicacion, ej: 1234567890ABCDEF];
$array_datos['jsonDevice'] = [json con toda la información del dispositivo];
$array_datos['jsonApp'] = [json con toda la información de la app];
$array_datos['jsonUser'] = [json con toda la información necesaria para el login];

$conexionapi = new spsApiNickcenter([RSA KEY PRIVADA asociada a su aplicación]);
$json_datos_devueltos = $conexionapi->getData('login', $array_datos);


  • rescuePassword: Mediante ésta tarea restauraremos la contraseña de usuarios previamente registrados en nuestro sistema y que no esten dados de baja.
    • app: Contendrá el hash de la aplicación dada de alta el panel de en Mobeleader.
    • country: Contendrá el país del dispositivo, necesario para comprobar si NickCenter esta activo para esa aplicación en ese país.
    • language: Idioma del dispositivo, necesario para las traducciones que se retornarán.
    • email: Email al que hay que restaurar la contraseña.
  • Ejemplo llamada directa: 
https://nickcenter.mobeleader.com/webservice_nickcenter.php?data=task=rescuePassword&app=[hash aplicacion, ej: 1234567890ABCDEF]&country=[código país, ej: ES]&language=[código idioma, ej: es]&email=[email a recuperar, ej: prueba@prueba.com]
  • Ejemplo spsApiNickcenter:
$array_datos = array();
$array_datos['app'] = [hash aplicacion, ej: 1234567890ABCDEF];
$array_datos['country'] = [código país, ej: ES];
$array_datos['language'] = [código idioma, ej: es];
$array_datos['email'] = [email a recuperar, ej: prueba@prueba.com];

$conexionapi = new spsApiNickcenter([RSA KEY PRIVADA asociada a su aplicación]);
$json_datos_devueltos = $conexionapi->getData('rescuePassword', $array_datos);

Retornos del Webservice

Cada tarea tendrá su propio JSON de retorno:

  • checkActive:
    • error: Indicará si ha habido un error o no.
    • errorTxt: En caso de haber un error indicará a que se debe dicho error.
    • active: Indicará si la aplicación esta activa o no.


  • requestFields:
    • error: Indicará si ha habido un error o no.
    • errorTxt: En caso de haber un error indicará a que se debe dicho error.
    • general: En caso de no haber ningún error devolverá un array con todas las traducciones generales para el idioma seleccionado.
    • fields: En caso de no haber ningún error devolverá un array con todos los campos y sus traducciones para el idioma seleccionado.


  • register:
    • error: Indicará si ha habido un error o no.
    • errorTxt: En caso de haber un error indicará a que se debe dicho error.
    • okTxt: En caso de no haber error indicará que el registro se ha completado.


  • update:
    • error: Indicará si ha habido un error o no.
    • errorTxt: En caso de haber un error indicará a que se debe dicho error.
    • okTxt: En caso de no haber error indicará que se ha actualizado correctamente.


  • login:
    • error: Indicará si ha habido un error o no.
    • errorTxt: En caso de haber un error indicará a que se debe dicho error.
    • okTxt: En caso de no haber error indicará que se ha logeado correctamente.


  • rescuePassword:
    • error: Indicará si ha habido un error o no.
    • errorTxt: En caso de haber un error indicará a que se debe dicho error.
    • okTxt: En caso de que no haya habido un error, se mandará una cadena en el idioma seleccionado, con las instrucciones para recuperar la contraseña.

Campos y Formatos

  • jsonDevice:
    • ua: User Agent. Es la cadena de texto que identifica al usuario ante el servidor que se esta conectando mediante HTTP. Campo obligatorio.
    • lmt: Limit Ad Tracking. Indicará si esta permitido el acceso al ifa del dispositivo. Campo obligatorio.
      • 0: Inactivo/Permitido.
      • 1: Activo/No permitido.
    • devicetype: Tipo de dispositivo. Campo obligatorio.
      • 4: Smartphone.
      • 5: Tablet/iPad.
    • make: Marca del dispositivo. Ejemplo: bq. Campo obligatorio.
    • model: Modelo del dispositivo. Ejemplo: Aquaris E5. Campo obligatorio.
    • os: Sistema operativo. Campo obligatorio.
      • Android: Android.
      • iOs: ios.
    • osv: Version del sistema operativo. Ejemplo: 6.0.1. Campo obligatorio.
    • hwv: Version del hardware. Ejemplo: Aquaris_E5. Campo obligatorio.
    • h: Altura de pantalla. Ejemplo: 1920. Campo obligatorio.
    • w: Anchura de pantalla. Ejemplo: 1080. Campo obligatorio.
    • ppi: Pixeles por pulgada. Ejemplo: 480. Campo obligatorio.
    • pxratio: Densidad de pixeles. Ejemplo: 3. Campo obligatorio.
    • inches: Pulgadas. Ejemplo: 4.9. Campo obligatorio.
    • js: Soporte para JavaScript. Campo obligatorio.
      • 0: No.
      • 1: Si.
    • connectiontype: Tipo de conexión. Campo obligatorio.
      • 0: Unknown.
      • 1: Ethernet.
      • 2: WiFI.
      • 3: Cellular Network - Unkown Generation.
      • 4: Cellular Network - 2G.
      • 5: Cellular Network - 3G.
      • 6: Cellular Network - 4G.
    • ifa: Identificador para la publicidad. Campo obligatorio, debe de estar o el ifa o el uuid.
      • Android: Google AID (Google Advertising Identifier). Ejemplo: 38400000-8cf0-11bd-b23e-10b96e40000d.
      • iOs: iOS IFA (Apple Identifier for Advertiser). Ejemplo: AAAAAAAAA-BBBB-CCCC-1111-222222220000.
    • uuid: Identificador único universal. Ejemplo: 550e8400-e29b-41d4-a716-446655440000. Campo obligatorio, debe estar el uuid o el ifa.
    • language: Idioma del dispositivo ( locale ). Ejemplo: es. Campo obligatorio.
    • country: Pais del dispositivo ( locale ). Ejemplo: ES. Campo obligatorio.
    • carrier: Operador Telefónico del dispositivo. Ejemplo: Movistar.
    • carriercode: Código del operador telefónico. Ejemplo: 21407.
    • carriercountry: País del operador telefónico. Ejemplo: ES.
    • mac: ( Solo para Android ) Mac del dispositivo. Ejemplo: 00:1B:44:11:3A:B7.
    • imsi: ( Solo para Android ) Identidad Internacional del Abonado Móvil. Ejemplo: 7160652952503786.
    • did: ( Solo para Android ) Identificador Direct inward dialing (DID).
    • dpid: ( Solo para Android ) Plataform device id (Android id).



  • jsonUser:
    • name: Nombre del usuario. Máximo 100 caracteres. Ejemplo: Kevin.
    • surname: Apellido del usuario. Máximo 100 caracteres. Ejemplo: Lancharro.
    • email: Email del usuario. Máximo 250 caracteres. Ejemplo: xxxx@xxx.com.
    • password: Password del usuario. Deberá ir en md5(). Máximo 50 caracteres. Ejemplo: e10adc3949ba59abbe56e057f20f883e.
    • nick: Nick del usuario. Máximo 50 caracteres. Ejemplo: CocoNilo.
    • phone: Teléfono móvil del usuario. Máximo 15 caracteres. Ejemplo: 6XX XXX XXX.
    • birthDate: Fecha de nacimiento del usuario. Ejemplo : 1992-01-12.
    • gender: Sexo del usuario.
      • Masculino: M.
      • Femenino: F.
    • allowsCommercials: Termino de privacidad con el que el usuario permite recibir comunicaciones comerciales.
      • Permite: yes.
      • Deniega: no.
    • allowsCession: Termino de privacidad con el que el usuario permite que sus datos sean cedidos a terceras empresas relacionadas con el sector.
      • Permite: yes.
      • Deniega: no.
    • Dependiendo de la tarea que estemos ejecutando los campos obligatorios variarán:
      • register: Dependerá de los campos que hayamos configurado en el apartado de NickCenter en el panel de Mobeleader, como mínimo siempre será obligatorio el email y el password.
      • update: El único campo obligatorio para las actualizaciones será el email, el resto de campos que se añadan serán los campos a actualizar.
      • login: Dependerá de los campos que hayamos configurado en el apartado de NickCenter en el panel de Mobeleader, será obligatorio el email o el nick, junto con el password. En cualquiera de los casos el password siempre será obligatorio.



  • jsonApp: Todos los campos son obligatorios
    • name: Nombre de la aplicación dada de alta en el panel de Mobeleader. Ejemplo: Mobeleader.
    • bundle: Nombre del paquete de la aplicación. Ejemplo: com.mobeleader.
    • version: Version de la aplicación. Ejemplo: 1.0.
    • versioncode: Código de versión de la aplicación. Ejemplo: 1.

Códigos de Errores

A continuación se expondrá una lista con los posibles errores que devolverá el Webservice en caso de que los datos no sean correctos:

  • Errores generales: Estos errores se deben a un mal uso de la clase spsApiNickcenter y/o su cifrado, por lo que al no poder devolver la cadena cifrada con la RSA Key pública que le corresponde a la aplicación, se mandarán en texto plano sin cifrar y sin formato JSON.
    • Error 000a - Failure decrypting
    • Error 000b - Invalid Task
    • Error 000c - Empty or invalid app hash
    • Error 000d - Missing public RSA Key for app hash X


  • Tarea checkActive:
    • Error 001a - Failure checking app active
    • Error 001b - Failure checking app active
    • Error 001c - Failure checking app active


  • Tarea rescuePassword:
    • Error 002a - Failure on rescuePassword
    • Error 002b - Failure on rescuePassword


  • Tarea requestFields:
    • Error 003a - Failure on requestFields
    • Error 003b - Failure on requestFields
    • Error 003c - Failure on requestFields


  • Tarea register/update/login:
    • Error 004a - Failure validating user json, there are no fields configured in your application
    • Error 004b - Failure validating user json, incorrect json format
    • Error 004c - Failure validating user json
    • Error 004d - X is missing or empty in user json.
    • Error 004e - Invalid format for X field in user json.


  • Tarea register/update/login:
    • Error 005a - Failure validating device json, incorrect json format
    • Error 005b - Failure validating device json
    • Error 005c - Field X is missing or empty in device json
    • Error 005c - Field ifa/uuid are missing or empty in device json, one of them must be informed


  • Tarea register/update/login:
    • Error 006a - Failure validating app json, incorrect json format
    • Error 006b - Field X is empty in app json
    • Error 006c - The bundle X for os Y, does not exist
    • Error 006c - Invalid X in app json, it must be numeric


  • Tarea register/update/login:
    • Error 007a - Failure generating library json, incorrect device json format
    • Error 007b - Failure generating library json, wrong os in device json
    • Error 007c - Failure generating library json, wrong os in device json


  • Tarea register:
    • Error 008a - Failure registering
    • Error 008b - Failure registering
    • Error 008c - Email already exists
    • Error 008c - Nick already exists


  • Tarea login:
    • Error 009 - Failure on login


  • Tarea update:
    • Error 010 - Failure updating


  • Sin tarea/Tarea erronea:
    • Error 011a - Empty Task
    • Error 011b - Invalid Task
Obtenido de «https://wiki.mobeleader.com/index.php?title=Documentación_Webservice_NickCenter&oldid=2743»