Revisión del 12:07 6 mar 2018

Introducción

En este documento se va a mostrar como ha de ser el contenido que se mande al api-xchange de Mobeleader para realizar las distintas acciones que ésta nos permite. Se expondrá brevemente como ha de realizarse la conexión a dicha API, como han de ser los campos obligatorios que han de ir para todos los casos y a continuación se procederá a tratar todos los casos con ejemplos para un mayor entendimiento.

Conectándonos a la API

Lo primero que deberemos hacer es solicitar el token necesario para la conexion a Mobeleader. Dicho token es un identificador único para cada usuario desarrollador. Una vez obtenido dicho token procederemos a hacer una breve prueba de conexión para comprobar que tenemos acceso a la API. En dicha prueba haremos uso de la tarea “ping”.

$token = 'token_generado_por_mobeleader';
$conexionapi = new spsapiXchange($token);

$json_datos_devueltos = $conexionapi->getData('ping');

En la imagen vemos como ha de ser el código necesario para realizar dicha prueba y el resultado transformado a un array. Si la posición del responsecode es “OK” significa que todo ha ido correctamente y en la posición data deberemos ver “pong”. Mientras esta prueba no de este resultado no podremos hacer ninguna acción más sobre la API.

Campos Obligatorios y No Obligatorios para las notificaciones

Para generar notificaciones desde nuestro sistema, en la conexión con la API deberá ir especificada la tarea “setPush”, junto un array de datos con una serie de campos.

Independientemente del SO al que la notificación irá, hay unos campos que son obligatorios; son los siguientes:

1. appHash: contendrá el hash autogenerado por el panel Mobeleader de la aplicación registrada.
2. terminalTokens: este campo podrá tener más de un formato, de manera que los dispositivos que reciban la notificación puedan ser diferentes.
   • En caso de tratarse de un array, se mandará la notificación a todos los tokens de dicho array.
   • En caso de no ser un array, podrá contener lo siguiente:
   1. all: En este caso se notificará a todos los dispositivos que estén registrados en la aplicación sin tener en cuenta el SO.
   2. onlyAndroid: Solo se notificará a los terminales con SO Android que estén registrados en la aplicación.
   3. onlyIOS: Solo se notificará a los terminales con SO IOs que estén registrados en la aplicación.
   4. Un token de un dispositivo en concreto, de manera que solo se le notifique a éste.
3. message: contendrá el texto de la notificación.
4. type: contendrá el tipo de notificación pudiendo ser este de de diversa índole.
   • normal: este tipo será el más común, el dispositivo recibirá la notificación y no se hará mas con ésta.
   • openApp: este tipo hará que al hacer click sobre la notificación se abra la aplicación encargada de mostrar dicha notificación.
   • openUrl: este tipo hará que al hacer click sobre la notificación se abra una URL especificada en otro campo que veremos más adelante.
   • openAppWithextras: este tipo hará lo mismo que el “openApp” pudiendo ademas añadir hasta cinco variables extra para poder tratarlas a nuestro gusto en la aplicación. Cabe destacar que este tipo de notificación, nos permitirá hacer uso de otro campo no obligatorio que más adelante trataremos, el cual se llama "customType” y nos permitirá lanzar notificaciones “personalizadas”.

Una vez vistos los campos obligatorios, a continuación se expondrán todos los campos no obligatorios que darán forma a las notificaciones:

1. tittle: contendrá el texto del título que se mostrara junto con el mensaje de la notificación.
2. sendingId: en caso de querer lanzar una notificación para muchos terminales, como hemos expuesto en los campos obligatorios, inicialmente el campo ”terminalTokens" deberá ser un array con dichos terminales. Debido a que la API no puede admitir un número ilimitado de tokens a la vez, deberemos segmentar dicho array en varios más pequeños y hacer tantos “setPush” como sean necesarios hasta finalizar con el número de dispositivos a notificar. Cada vez que nos conectemos a la API para hacer un “setPush” y generar una notificación, dicha conexión nos devolverá un JSON en el cual hay un campo denominado “sendingId” con el ID autonumérico generado en nuestro sistema para ese envío push. De ésta manera, si se recoge dicho ID y se pasa como campo en la posición “sendingId”, los siguientes tokens que se manden en el ”terminalTokens” irán asociados al primer envío realizado.
3. sandbox: este campo solo se usará cuando se vaya a notificar a algún dispositivo con SO iOs. Contendrá “yes” en caso de que dicho dispositivo este en el servidor de desarrollo de Apple, y un “no” en caso de que dicho dispositivo este en el servidor de producción de Apple.
4. isTest: al igual que en el campo del “sandbox”, contendrá “yes” o “no” dependiendo de si el dispositivo esta en el servidor de desarrollo o el de producción de Apple.
5. background: este campo solo irá en caso de ir a algún dispositivo que tenga SO iOs. Contendrá “yes” o “no”. En caso de ser afirmativo la notificación se mostrará sin hacer ruido ni vibrar. Para el caso de iOs esto generará un alert vació con el content-available a 1.
6. silent: Contendrá “yes” o “no”. En caso de ser afirmativo la notificación no se mostrará pero si lanzará el evento de la librería push encargado de escuchar si se ha recibido una notificación o no. De ésta manera podremos lanzar notificaciones que no se muestren, pero si hagan algo por detrás en la APP al recibirla. Para el caso de Android solo se usará este campo cuando el “type” de la notificación sea “openAppWithExtras” y se haga uso del campo no obligatorio “customType”. Para el caso de iOs esto generará un alert vació con el content-available a 1 por defecto, pudiendo ser modificado por el siguiente campo que se expone a continuación ( silentNumber ). Como en el caso de Android esto solo tendrá sentido para las notificaciones de “type” “openAppWithExtras” , puesto que al no mostrar nada, se usarán para hacer cosas por detrás mediante los campos no obligatorios external1, external2, external3, external4 y external5. A diferencia de Android, en iOs se podrá usar con ”customType” o sin el.
7. silentNumber: este campo solo se usará para SO iOs. Es el número que aparecerá en el content-available en caso de que el campo silent sea "yes".
8. customType: contendrá el texto del tipo de notificación personalizada que cada uno cree. Éste campo solo se podrá usar si previamente en el campo obligatorio “type” se ha puesto “openAppWithExtras”.
9. badge: este campo será el número que se mostrará junto con la notificación en los dispositivos SO iOs. A partir de iOs 10 las notificaciones no levantan la aplicación en caso de estar background, por lo que esto generará un content-available con el fin de despertar la aplicación y poder actualizar el icono de notificaciones pendientes en ésta.
10. broadcast: esta variable solo será útil para dispositivos con SO Android, contendrá el nombre de la clase instanciada en su aplicación para que se active al recibir la notificación.
11. direct: contendra "yes" o "no". En caso de ser afirmativo las notificaciones se enviarán al instante no pudiendo programarlas.
12. whenSend: contendrá “immediately”, “programmatically” o “geolocation”. En caso de ser immediately el campo “direct” previamente descrito deberá ser “yes”. En caso de ser “programmatically” o “geolocation” el campo “direct” previamente descrito deberá ser “no”, ademas el envío se programará según los siguientes campos no obligatorios que se le pase.
    • Programmatically: cuando la notificación se quiera programar para una fecha en concreto , deberán existir los siguientes campos no obligatorios:
    1. programmaticallyTime: contendrá la fecha en UNIXTIMESTAMP en la que se lanzará la notificación, si se usa este campo no obligatorio no deberemos usar los siguientes.
    2. programmaticallyCronMinutes:
    3. programmaticallyCronHours:
    4. programmaticallyCronDays:
    5. programmaticallyCronMonths:
    • Geolocation: cuando se quiera programar por geolocalización una notificación, deberán existir los siguientes campos no obligatorios:
    1. geolocationCoordinates: será un array en el que la posición cero será la latitud y la uno la longitud.
    2. geolocationMeters: contendrá los metros a los que hemos de estar de las coordenadas especificadas para que lance la notificación.
13. languaje: contendrá el idioma del dispositivo. Ejemplo: es.
14. country: contendrá el país del dispositivo. Ejemplo: ES.
15. deviceType: contendrá el tipo de dispositivo al que se le mandará la notificación pudiendo ser:
    • Para Android:
    1. movil.
    2. tableta.
    3. reloj.
    4. tv.
    • Para iOs:
    1. iphone.
    2. ipad.
    3. iwatch.
    4. appletv.
16. appVersion: contendrá la versión de la aplicación a la que esta dirigida la notificación. Ejemplo: 1.0.1.
17. terminalVersion: contendrá la versión del terminal al que ira dirigida la notificación. Ejemplo: 6.0.1.
18. urlToOpen: contendrá la URL a abrir al hacer click sobre una notificación de tipo “openUrl”.
19. external1: variable extra que contendrá lo que el usuario quiera para tratar en las notificaciones de tipo “openAppWithExtras” y/o “openAppWithExtras” con “customType”.
20. external2: variable extra que contendrá lo que el usuario quiera para tratar en las notificaciones de tipo “openAppWithExtras” y/o “openAppWithExtras” con “customType”.
21. external3: variable extra que contendrá lo que el usuario quiera para tratar en las notificaciones de tipo “openAppWithExtras” y/o “openAppWithExtras” con “customType”.
22. external4: variable extra que contendrá lo que el usuario quiera para tratar en las notificaciones de tipo “openAppWithExtras” y/o “openAppWithExtras” con “customType”.
23. external5: variable extra que contendrá lo que el usuario quiera para tratar en las notificaciones de tipo “openAppWithExtras” y/o “openAppWithExtras” con “customType”.
24. androidNotyStyle: contendrá “bigPictureStyle” cuando queramos mostrar una imagen junto con la notificación en los dispositivos con SO Android. En caso de no querer mostrar ninguna imagen no se utilizara este campo.
25. bigPictureStyleUrlImage: contendrá la URL de la imagen que se quiera mostrar en los dispositivos con SO Android, siempre habiendo hecho uso del campo previamente expuesto “androidNotyStyle” con el contenido “bigPictureStyle". Cabe destacar que la URL deberá ser segura ( https ) y deberá contener la extension del contenido en dicha URL.
26. bigPictureStyleExpandedTitle: contendrá el texto que se mostrará como titulo al expandir una notificación que contenga una imagen en dispositivos con SO Android, siempre habiendo hecho uso del campo previamente expuesto “androidNotyStyle” con el contenido “bigPictureStyle”.
27. bigPictureStyleExpandedSumaryText: contendrá el texto que se mostrará como mensaje al expandir una notificación que contenga una imagen en dispositivos con SO Android , siempre habiendo hecho uso del campo previamente expuesto “androidNotyStyle” con el contenido “bigPictureStyle”.
28. extra-content: este campo solo se usará para notificaciones dirigidas a dispositivos con SO iOs. Contendrá la URL del contenido extra que se quiere mostrar junto con la notificación. En este caso y a diferencia de Android ( bigPictureStyleUrlImage ), dicho contenido podrá ser una imagen, un giff, un video o un audio. La URL también deberá ser segura ( https ) y deberá contener la extension del contenido en dicha URL.
29. channel: A partir de Android O, las notificaciones deberán ir por un canal de notificaciones instanciado en su aplicación. Esta variable contendrá el nombre del canal por el que han de salir.

Notificaciones Android

En este apartado veremos los distintos tipos de notificaciones para dispositivos Android mas detalladamente complementándolo con ejemplos funcionales:

1. normal:
   1. Con imagen:

$token = 'token_generado_por_mobeleader';
$conexionapi = new spsapiXchange($token);

$arr_data = array();
$arr_data['appHash'] = 'token_de_la_aplicacion_registrada';
$arr_data['direct'] = "yes";
$arr_data['whenSend'] = "inmediately";
$arr_data['type'] = 'normal';
$arr_data['title'] = 'Titulo Noti.Normal+IMG';
$arr_data['message'] = 'Mensaje Noti.Normal+IMG';
$arr_data['terminalTokens'] = 'onlyAndroid';
$arr_data['androidNotyStyle'] = 'bigPictureStyle';
$arr_data['bigPictureStyleUrlImage'] = 'url_image';
$arr_data['bigPictureStypeExpandedTittle'] = 'Titulo Noti.Expandida';
$arr_data['bigPictureStyleExpandedSumaryText'] = 'Mensaje Noti.Expandida';

$json_datos_devueltos = conexionapi->getData('setPush', $arr_data);

1. 1. Sin imagen:

$token = 'token_generado_por_mobeleader';
$conexionapi = new spsapiXchange($token);

$arr_data = array();
$arr_data['appHash'] = 'token_de_la_aplicacion_registrada';
$arr_data['direct'] = "yes";
$arr_data['whenSend'] = "inmediately";
$arr_data['type'] = 'normal';
$arr_data['title'] = 'Titulo Noti.Normal';
$arr_data['message'] = 'Mensaje Noti.Normal';
$arr_data['terminalTokens'] = 'onlyAndroid';

$json_datos_devueltos = conexionapi->getData('setPush', $arr_data);

1. openApp:
   1. Con imagen:
   2. Sin imagen:
2. openUrl:
   1. Con imagen:
   2. Sin imagen:
3. openApppWithExtras:
   1. Con customType:
      1. Con imagen:
      2. Sin imagen:
      3. Sin notificación:
   2. Sin customType:
      1. Con imagen:
      2. Sin imagen:
4. Independientemente de los anteriores tipos:
   1. sendingId:
   2. language:
   3. country:
   4. deviceType:
   5. appVersion:
   6. terminalVersion:

Notificaciones iOs

En este apartado veremos los distintos tipos de notificaciones para dispositivos iOs mas detalladamente complementándolo con ejemplos funcionales:

1. • normal:
   1. Con imagen:
   2. Sin imagen:
   • openApp:
   1. Con imagen:
   2. Sin imagen:
   • openUrl:
   1. Con imagen:
   2. Sin imagen:
   • openApppWithExtras:
   1. Con customType:
      1. Silenciosa:
   2. Sin customType:
      1. Silenciosa:
   • Independientemente de los anteriores tipos:
   1. sendingId:
   2. language:
   3. country:
   4. deviceType:
   5. appVersion:
   6. terminalVersion:

Respuesta setPush

La respuesta que recibiremos por parte de la API siempre será un JSON. Dicho JSON contendrá de tres a cinco posiciones/elementos:

1. responsecode: determinará si la acción a realizar sobre la API ha funcionado o no. En caso de ser negativo devolverá “KO” y en caso de ser positivo será “OK”.
2. errorcode: en caso de que el responsecode sea “KO”, devolverá el código de error en nuestro sistema. Por el contrario, si el responsecode es “OK”, devolverá un 0.
3. errortext: contendrá el texto del error que se ha producido, por lo que como se deduce esto solo saldrá cuando la acción sobre la API no se haya podido ejecutar.
4. data: contendrá el resultado de la acción realizada satisfactoriamente sobre la API. Si ha habido un error esta posición no se generará.
5. timestamp: devolverá la fecha en timestamp en la que la acción sobre la API ha sido realizada correctamente. Si ha habido un error esta posición no se generará.

En resumen, si la acción a realizar sobre la API ha dado error, el JSON contendrá los elementos ( responsecode, errorcode y errortext).

Por el contrario si la acción ha finalizado correcta y satisfactoriamente, el JSON contendrá los elementos ( responsecode, errorcode, data y timestamp). Para el caso de crear una notificación ( setPush ), y que haya funcionado correctamente, en la respuesta se generará algo tal que la siguiente imágen:

En el contenido del elemento data, se mostrara las notificaciones que se han podido enviar, las que no se han podido enviar, el ID que se genera en nuestro sistema asociado al envío solicitado y un array con los tokens enviados ( deletedArray ) y un array con los tokens que no se han podido enviar ( deletedWithoutSend ).

Este último caso, el del array con los tokens que no se han podido enviar solo se informará en el caso de que al enviar la acción setPush, en la posición terminalTokens, se mande un array con los terminales en concreto que se quieren notificar.

En el caso del array con los dispositivos notificados, se apreciará una segmentación por SO. En caso de que uno de estos dispositivos no haya podido recibir la notificación por problemas como bien puede ser un token obsoleto, se borrará de nuestro sistema y el token se informará en la posición ( deletedTokens ).

Obtención de usuarios registrados en su aplicación

Para obtener un conteo de usuarios registrados en nuestra aplicación y los datos de estos, deberemos hacer uso de la tarea “getPushTokens” y el hash de la aplicación registrada en el panel de Mobeleader. Dicho hash podremos verlo en cualquier momento desde la sección https://panel.mobeleader.com/index.php?sec=6. Una vez obtengamos dicho hash procederemos a conectarnos a la API de la manera expuesta en la a continuación:

$token = 'token_generado_por_mobeleader';
$conexionapi = new spsapiXchange($token);

$arr_data = array();
$arr_data['appHash'] = 'token_de_la_aplicacion_registrada';

$json_datos_devueltos = $conexionapi->getData('getPushTokens', $arr_data);

Como se puede apreciar en la respuesta, la posición respondecode es “OK”. Al igual que en el caso del “ping”, siempre que el responsecode sea ”OK” significara que la acción a realizar sobre la API ha finalizado correctamente y que en la posición “data” vendrá los solicitado, en este caso los datos de los terminales registrados en la aplicación.

Borrado de usuarios registrados en su aplicación

Una vez obtenidos los datos mediante la tarea “getPushTokens”, si quisiéramos borrar alguno de dichos tokens del sistema de Mobeleader, deberemos hacer uso de la tarea “deletePushTokens” usando el hash de la aplicación de la misma manera que en la obtención de usuarios, y pasándole el token o los tokens que quisiéramos borrar. Lo haremos de la siguiente manera:

$token = 'token_generado_por_mobeleader';
$conexionapi = new spsapiXchange($token);

$arr_data = array();
$arr_data['appHash'] = 'token_de_la_aplicacion_registrada';
$arr_data['tokens'][] = 'token_del_usuario_registrado';

$json_datos_devueltos = $conexionapi->getData('deletePushTokens', $arr_data);

Como siempre, en caso de que el responsecode sea “OK”, en la posición “data” veremos el número de tokens borrados.