Guía de integración de servicios

Una vez configurado el proyecto en la Consola de APIs de Google, generado los archivos correspondientes y añadidos los parámetros necesarios a la configuración de la Consola de Octopush, será necesaria la integración del cliente en nuestra aplicación Android.

Configuracion

Se ha de crear una instancia singleton de la clase Octopush para hacer uso de la librería con garantías. Esta instancia se crea a través de un patrón builder cuyo constructor recibe el contexto de una aplicación.

Ejemplo de instancia en Application

Creación

MyApplication extends Application{

private static MyApplication application;
private static Octopush octopush;
...
@Override
    public void onCreate() {
        super.onCreate();
        application = this;
        octopush = new Octopush.Builder(this).build();
    }

public static Octopush getOctopush(){
    return octopush;
}
...
}

Uso

public class MainActivity extends Activity{
 @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        MyApplication.getOctopush().registerByDevice(this);
    }

}

Ejemplo de instancia singleton con Dagger 2

Creación

@Provides
@Singleton
Octopush provideOctopush(Application application){
      return new Octopush.Builer(application).build();
}

Uso

public class MainActivity extends Activity{

@Inject
Octopush octopush;

 @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        octopush.registerByDevice(this);
    }

}

Registrar

Registrar dispositivo

void registerByDevice(OctopushCallback.Empty callback);

Sirve para registrar el dispositivo en Octopush. Si la configuración es correcta, en este momento la aplicación ya podrá recibir notificaciones.

public class MyApplication extends Application {

@Inject
Octopush octopush;

@Override
public void onCreate() {
    super.onCreate();
    octopush.registerByDevice(new OctopushCallback.Empty() {
                @Override
                public void onSuccess() {
                    //TODO SUCCESS FLOW
                }

                @Override
                public void onError(OctopushError error) {
                    //TODO ERROR FLOW
                }
            });                ...
  }
        ...
}

Octopush tiene un método para comprobar si el dispositivo está registrado:

boolean isRegister();

 

Registrar usuario

void registerByUser(String idUser, OctopushCallback.Empty callback);

Podemos enviar notificaciones push dirigidas a usuarios. De esta forma se enviarán notificaciones a varios dispositivos si estos están registrados con el mismo usuario. El usuario se envía a Octopush como una cadena de texto, por lo tanto, es responsabilidad del desarrollador proporcionar un identificador adecuado (sensible a mayúsculas). Disponemos de un método para saber si se está registrado por usuario y otro para obtener la id del usuario que está registrado en el dispositivo.

boolean isUserRegister();
String getUserId();

Desregistrar dispositivo

void unRegister(OctopushCallback.Empty callback);

Usaremos este método para dejar de recibir notificaciones dando de baja el dispositivo en Octopush.

 

 Plantillas y acciones 

Octopush nos provee de una serie de plantillas para enviar notificaciones push a los clientes móviles. En la actualidad son 6 las plantillas que se pueden usar desde la consola:

Octopush templates

Para cualquiera de estas plantillas podemos definir la acción que realizará la notificación en el momento en que el usuario pulse sobre ella. En la configuración por defecto del cliente Android, esta acción es la de abrir la aplicación o pasarla a primer plano si no lo está.

Si queremos realizar otras acciones tendremos que configurarlas tanto en la consola como en la aplicación.

 Acciones personalizadas

Consola
  • En primer lugar hemos de crear la acción en la consola de Octopush, vamos a la opción Ajustes -> Botones de acción.

oct_create_action

 

  • Definimos la acción con una clave (Alias Acción), el nombre que tendrá, la prioridad (1 si sólo se puede poner en el botón izquierdo, 2 si es el derecho o ambas si se puede configurar en cualquiera de los dos botones de la notificación) y opcionalmente la descripción de la acción.
  • Pulsamos la opción Crear
  • Podemos ver la nueva acción en la lista de acciones de la aplicación.

oct_list_action

App
  • Crear un Receiver que extiende de OctopushReceiver con las claves definidas en la consola de Octopush.
public class TestActionReceiver extends OctopushReceiver
  • Sobreescribir el método handleActions y en una cláusula switch/case definir lo que hace cada acción. Además se debe mantener por defecto el abrir la aplicación.
    public static final String ACTION_HELLO = "Hola";
     public static final String ACTION_BYE = "Adios";
     
     @Override
     public void handleActions(Context context, String action, Intent intent, HashMap<String, String> extras) {
         switch (action) {
             case ACTION_HELLO:
                 onHelloAction(context, intent);
                 break;
             case ACTION_BYE:
                 onByeAction(context, intent);
                 break;
             default:
                 performDefaultBehaviour(context, intent);
                 break;
         }
     }
  • Una vez definido, hay que substituir en el AndroidManifest la clase del intent-filter .OCTOPUSH_REVEIVER con el nombre de la clase que hemos creado.
    <application>
    ...
        <receiver android:name="com.sdos.testoctopush.ui.receiver.TestActionReceiver">
            <intent-filter>
                <action android:name="${applicationId}.OCTOPUSH_RECEIVER" />
            </intent-filter>
         </receiver>
    ...
     </application>
  • Por último, en la inicialización de Octopush, indicamos la class del nuevo Receiver.
octopush = new Octopush.Builder(this)
            .receiver(TestActionReceiver.class)
            .build();
Envío de notificaciones y acciones

Tal y como hemos comentado, para todas las plantillas se puede modificar que hace la notificación al pulsarla, asociando una acción definida.

Para asociar a la plantilla con botones acciones a cada uno de ellos, debe de haber disponible acciones con prioridad que permita asignar la acción al botón correspondiente. Como hemos dicho, para que se pueda asignar una acción al botón izquierdo dicha acción debe tener prioridad 1 o ambas. Para que se pueda asociar una acción al botón derecho esta debe ser prioridad 2 o ambas.

 

oct_add_action
 

Tracker

La librería cliente de Octopush cuenta con una funcionalidad de tracking de la posición del dispositivo. Necesitamos de configurar nuestro proyecto adicionalmente para poder usar esta utilidad.

Configuración

En nuestro AndroidManifest.xml, hay que añadir el permiso que permite obtener la información de localización del dispositivo. Además, tendremos que declarar el servicio de localización.

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Uso

Habilitar tracker

void enableTracker(Activity activity, OctopushTracker octopushTracker, boolean checkPermissions);

Podemos definir dos variables en el tracker:

class OctopushTracker{
 boolean sendImmediately // Envía la posición justo al habilitar o espera al intervalo definido
 long interval // Intervalo de repetición entre envío expresado en milisegundos. 
               //Por defecto el intervalo es de 12 horas, siendo el mínimo de 1 minuto.
}

Gestión versiones a partir de API 23

  1. Definimos un boolean para la gestión de la activación de la localización y un broadcastReceiver para realizar la petición al sistema operativo.
class MainActivity extends Activity {

@Inject
Octopush octopush

private Boolean activeLocationReceiverIsRegistered = false;

private BroadcastReceiver activeLocationReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            if (intent != null && intent.getExtras() != null && intent.getExtras().containsKey(OctopushNotificationConstants.OCTOPUSH_REQUEST)) {
                int message = intent.getIntExtra(OctopushNotificationConstants.OCTOPUSH_REQUEST, 0);
                if (message == OctopushConstants.OCTOPUSH_LOCATION_REQUEST_ACTIVATION_CLIENT_KEY) {
                    octopush.requestLocationSettings(MainActivity.this);
                }
            }
        }
    };

...
}

2. Tenemos que registrar y desregistrar el BroadcastReceiver acorde al ciclo de vida de la Activity

  • class MainActivity extends Activity{
    ...
    
    @Override
        public void onResume(){
            super.onResume();
            if (!activeLocationReceiverIsRegistered) {
                LocalBroadcastManager.getInstance(this).registerReceiver(activeLocationReceiver, new IntentFilter(OctopushConstants.OCTOPUSH_REQUEST_LOCATION_CLIENT_KEY));
                activeLocationReceiverIsRegistered = true;
            }
        }
    
        @Override
        public void onPause(){
            super.onPause();
            if (activeLocationReceiverIsRegistered) {
                LocalBroadcastManager.getInstance(this).unregisterReceiver(activeLocationReceiver);
                activeLocationReceiverIsRegistered = false;
            }
        }
    
    ...
    }

3. Habilitar el tracker en 3 sitios:

  • Al gestionar el permiso de usar la localización
  • Al gestionar el permiso de habilitar la localización
  • Donde queremos habilitarlo
  • OctopushTracker tracker = new OctopushTracker.Builder().sendImmediately(true).interval(12000L).build();
    
        private void clickOnStartTracker(){
            octopush.enableTracker(this, tracker, true); // Aquí le damos valor true a checkPermissions para gestionar el permiso de localización.
        }
        @Override
        public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
            switch (requestCode) {
                case OctopushConstants.OCTOPUSH_LOCATION_REQUEST_PERMISSION_CLIENT_KEY:
                    if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                        octopush.enableTracker(this, tracker, false); // Aquí ya está gestionado el permiso
                    }
                    break;
            }
        }
    
        @Override
        protected void onActivityResult(int requestCode, int resultCode, Intent data) {
            switch (requestCode) {
                case OctopushConstants.REQUEST_CHECK_SETTINGS:
                    switch (resultCode) {
                        case Activity.RESULT_OK:
                            octopush.enableTracker(this, tracker, false); // Aquí también está gestionado el permiso
                            break;
                        case Activity.RESULT_CANCELED:
                            break;
                    }
                    break;
            }
        }

    Deshabilitar tracker

    void disableTracker();

    Obtener el estado del tracker

    Pair<Boolean, Long> getTrackerState();
  • El primer valor del par devuelve si está o no habilitado el tracker.
  • El segundo valor del tracker devuelve el intervalo establecido.

Segmentación

Para ofrecer una mejor experiencia a los usuarios y una mejor distribución de la información, Octopush implementa un sistema de segmentación de envíos push. Podremos seleccionar a que dispositivos queremos enviar la información dependiendo de los segmentos definidos en la consola de Octopush seleccionados en un dispositivo. Por ejemplo, podremos definir el envío de publicidad de bebidas alcohólicas a los usuarios mayores de 18 años. Los segmentos no pueden crearse desde la aplicación Android, deben ser administrados desde la consola de Octopush.

Tipos

Un segmento es la representación de un valor para una propiedad. De esta forma, podemos definir a quien enviamos notificaciones después de aplicar ciertos operadores sobre dichos valores. Por ejemplo, podemos definir un segmento de tipo fecha y aplicar un operador “Mayor que” para discriminar dispositivos en los cuales se haya establecido este segmento con una fecha anterior.

Existen varios tipos de segmentos para abarcar el máximo abanico de posibilidades a la hora de diseñar una política de segmentación:

  • Tipo texto: nos permitirá establecer una cadena de texto como valor de un segmento.
  • Tipo numérico: nos permitirá establecer un número decimal como valor de un segmento.
  • Tipo fecha: nos permitirá establecer una fecha dada por día, mes y año, como valor de un segmento.
  • Tipo booleano: nos permitirá establecer si/no como valor de un segmento.
  • Tipo opción múltiple: este segmento define a su vez un listado de opciones que cuentan con la propiedad “seleccionada/no seleccionada”.

 Servicios

Los métodos de la librería de Octopush relacionados con la segmentación son los siguientes:

void getSegments(OctopushCallback.Multiple<OctopushSegment> callback);
  • Obtiene todos los segmentos disponibles para esta aplicación desde la consola de Octopush.
void getSegmentById(String segmentId, OctopushCallback.Single<OctopushSegment> callback);
  • Obtiene el segmento con el identificador proporcionado por parámetros.
void setAllSegments(List<OctopushSegment> segments, OctopushCallback.Multiple<OctopushSegment> callback);
  • Establece los segmentos para un dispositivo en el sistema Octopush. Este método sobrescribe la información en el sistema, por lo que la lista de segmentos que recibe este método será la usada para enviar notificaciones al dispositivo.
void setSegments(List<OctopushSegment> segments, OctopushCallback.Multiple<OctopushSegment> callback);
  • Actualiza los segmentos para un dispositivo en el sistema Octopush. Los segmentos contenidos en la lista se modificarán en el sistema, mientras que los demás no se verán afectados.
void setSegment(OctopushSegment segment, OctopushCallback.Single<OctopushSegment> callback);
  • Actualiza el segmento enviado para un dispositivo en el sistema Octopush.

*Nota: Los segmentos pertenecen a un dispositivo o a un usuario pero estos no se almacenan localmente, todas las operaciones de guardado y recuperación se hacen contra el servidor.
 

Mensajes rich

Octopush tiene una funcionalidad para enviar notificaciones rich, que son notificaciones con contenido Html, título, descripción y vigencia, que pueden estar o no asociadas a notificaciones push y deben de tratarse de manera especial.

A partir de la versión 5.1.X de la librería, los filtros por usuario y dispositivos van intrínsecamente en las peticiones al servidor dependiendo del tipo de registro contra Octopush realizado.

Lista de Riches por filtro

void getRichesByFilter(OctopushRichFilter filter, OctopushCallback.Multiple<OctopushRichMessage> callback);
  • Las posibilidades de filtrado son las siguientes:
    class OctopushRichFilter{
     String cipherId; // Id de la rich
     Boolean sendPush; // Tiene push asociada
     Boolean read; // Ha sido leída
     Boolean expired; // Ha expirado
     Boolean valid; // Es válida
     Date validityStartDate; // Fecha inicio validez
     Date validityEndDate; // Fecha fin validez
    }

Obtener Rich por id

void getRichById(String idRich, OctopushCallback.Single<OctopushRichMessage> callback);
  • Obtiene un mensaje rich por id si existe.

Obtener Rich por id marcándola como leída

void getRichAndMarkAsReadById(String idRich, OctopushCallback.Single<OctopushRichMessage> callback);
  • Además de obtener el mensaje rich si existe, lo marca como leído.

Marcar Rich como leída por id

void markRichAsReadById(String idRich, OctopushCallback.Empty callback);
  • Marca como leído el mensaje rich con este id si existe.

 

Personalización

Recepción de notificaciones

El cliente de Octopush para Android ya se encarga de mostrar notificaciones nativamente con la plantilla que seleccione en la consola.

Sin embargo, es posible cambiar este comportamiento y personalizar la forma en que se notifica en el dispositivo. Para realizar esta personalización hay que definir un servicio que extienda de GcmListenerService en el caso de GCM y un servicio que extienda de FirebaseMessagingService para FCM y sobrescribir el método de recepción:

Cliente GCM
public class OctopushMessageListenerService extends GcmListenerService {
 
     @Override
     public void onMessageReceived(String from, Bundle data) {
      //Get data from bundle
     }
 }
Android Manifest GCM

Una vez definido el servicio, debe de ser añadido al AndroidManifest.xml para GCM

<application>
<service
		android:name="es.sdos.octopush.services.OctopushMessageListenerService"
		android:exported="false">
		<intent-filter>
			<action android:name="com.google.android.c2dm.intent.RECEIVE"/>
		</intent-filter>
</service>
</application>
Cliente FCM
public class OctopushMessageListenerService extends FirebaseMessagingService {
 
     @Override
     public void onMessageReceived(RemoteMessage message){
      //Get data from message
     }
 }
Android Manifest FCM

Una vez definido el servicio, debe de ser añadido al AndroidManifest.xml para FCM

<application>
<service 
	android:name="es.sdos.octopush.services.OctopushMessageListenerService"
	android:exported="false">
	<intent-filter>
		<action android:name="com.google.firebase.MESSAGING_EVENT"/>
	</intent-filter>
</service>
</application>

Personalización de notificaciones 

Próximamente se proveerá a Octopush de métodos para personalizar las notificaciones.

 

Guía de integración de servicios