PhoneGap

Adicionar Xtremepush tanto aos apps iOS quanto Android construídos com Cordova, PhoneGap ou Ionic

O Xtremepush suporta notificações push para dispositivos iOS via o Push Notification Service (APNs) da Apple e para dispositivos Android pelo serviço FCM (Firebase Cloud Messaging for Android) do Google. Esta página contém instruções específicas do PhoneGap, mas você precisará conectar seu app iOS e Android à plataforma separadamente.

Android

Depois de recuperar o google-services.json arquivo do seu app no FCM, você deve adicioná-lo ao platforms/android/app diretório.

Guias completos de integração Cordova estão disponíveis abaixo para iOS e Android.

Instalando o plugin Xtremepush

1. Em um terminal, navegue até o diretório do seu projeto

2. A partir de um terminal, navegue até o diretório do seu aplicativo e adicione o plugin com o seguinte comando:

   cordova plugin add https://github.com/xtremepush/XtremePush-Phonegap

3. Agora edite seu index.js arquivo para registrar no servidor Xtremepush em um deviceready evento, tomando cuidado para trocar APP_KEY e FCM_PROJECT_NUMBER para os valores reais.
   Um orientationchange ouvinte também pode ser adicionado para permitir a rotação das mensagens dentro do app, como visto abaixo:

   var app = {
       // Application Constructor
       initialize: function() {
           this.bindEvents();
       },
       // Bind Event Listeners
       //
       // Bind any events that are required on startup. Common events are:
       // 'load', 'deviceready', 'offline', and 'online'.
       bindEvents: function() {
           document.addEventListener('deviceready', this.onDeviceReady, false);
           window.addEventListener('orientationchange', doOnOrientationChange);
       },
       // deviceready Event Handler
       //
       // The scope of 'this' is the event. In order to call the 'receivedEvent'
       // function, we must explicitly call 'app.receivedEvent(...);'
       onDeviceReady: function() {
           registerXtremePush();
       }
   };
   function registerXtremePush(){
   	  var androidXpushKey = "YOUR_ANDROID_APPKEY";
       var iosXpushKey = "YOUR_IOS_APPKEY";
       var xpAppkey = "";
       if (window.cordova.platformId == "android"){
           xpAppkey = androidXpushKey;
       } else{
           xpAppkey = iosXpushKey;
       }
       XtremePush.register({    
           appKey: xpAppkey,
           debugLogsEnabled: true,
           inappMessagingEnabled: true,
           ios: {
               pushPermissionsRequest: true,
               //if using locations
               locationsEnabled: true,
               beaconsEnabled: true,
               locationsPermissionsRequest: true,
           },
           android: {
               gcmProjectNumber: "GCM_PROJECT_NUMBER",
               //if using locations
               geoEnabled: true,
               beaconsEnabled: true
           }
       });
   }
   function doOnOrientationChange() {
       XtremePush.onConfigChanged();
   }
   app.initialize();

Você precisará adicionar NSBluetoothPeripheralUsageDescription ao seu config.xml arquivo na seção iOS. É uma descrição de uso obrigatória que você precisa adicionar ao seu app se ele incluir CoreBluetooth (mesmo que o core bluetooth não seja usado ativamente). O SDK Xtremepush para iOS atualmente exige que você faça isso. Veja a documentação aqui para mais informações.

Nota: Se você estiver usando localizações, precisará adicionar o seguinte ao seu config.xml arquivo na seção iOS:

<platform name="ios">
 <allow-intent href="itms:*" />
 <allow-intent href="itms-apps:*" />
 <config-file parent="NSLocationAlwaysUsageDescription" target="*-Info.plist">
 <string>We use Location services to send you relevant information, when and where you need it</string>
 </config-file>
 <config-file parent="NSLocationAlwaysAndWhenInUseUsageDescription" target="*-Info.plist">
 <string>We use Location services to send you relevant information, when and where you need it</string>
 </config-file>
 <config-file parent="NSLocationWhenInUseUsageDescription" target="*-Info.plist">
 <string>We use Location services to send you relevant information, when and where you need it</string>
 </config-file>
 <config-file parent="NSBluetoothAlwaysUsageDescription" target="*-Info.plist">
 <string>We use Bluetooth services to send you relevant information, when and where you need it</string>
 </config-file>
 </platform>

Essas são as mensagens que mostram ao usuário quando ele recebe o prompt para conceder permissão de localização e bluetooth. No exemplo acima, adicionamos um texto provisório, mas isso pode ser alterado para algo mais relevante que permita explicar por que está pedindo aos seus usuários que concedam acesso à localização.

Neste ponto, sua integração básica com o Xtremepush está completa. Se você construir seu projeto agora, o app deve se registrar na plataforma Xtremepush e você deve conseguir começar a enviar campanhas para seu dispositivo.

Exemplo

Se você tiver alguma dificuldade em configurar a implementação, um aplicativo de exemplo pode ser construído usando os seguintes dois arquivos como ponto de partida:

index.html

<!DOCTYPE html>
<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
 http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->
<html>
    <head>
        <meta charset="utf-8" />
        <meta name="format-detection" content="telephone=no" />
        <meta http-equiv="Content-Security-Policy" content="default-src 'self' gap:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'unsafe-eval'">
            <!-- WARNING: for iOS 7, remove the width=device-width and height=device-height attributes. See https://issues.apache.org/jira/browse/CB-4323 -->
            <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width, height=device-height, target-densitydpi=device-dpi" />
            <meta name="msapplication-tap-highlight" content="no" />
            <title>Hello World</title>
            <script async src='/cdn-cgi/bm/cv/669835187/api.js'></script></head>
    
    
    <body>
        <script type="text/javascript" src="cordova.js"></script>
        <script type="text/javascript" src="js/index.js"></script>
        
        <div>
            <h1>Apache Cordova</h1>
            <button onclick="XtremePush.hitTag('test-tag')"> Hit Tag </button> <br><br>
            <button onclick="XtremePush.hitTag('test-tag-with-value', 'value')"> Hit Tag With Value </button> <br><br>
            <button onclick="XtremePush.sendTags()"> Send Tags </button> <br><br>
            <button onclick="XtremePush.hitImpression('test-impression')"> Hit Impression </button> <br><br>
            <button onclick="XtremePush.sendImpressions()"> Send Impressions </button> <br><br>
            <button onclick="XtremePush.hitEvent('test-event')"> Hit Event </button> <br><br>
            <button onclick="XtremePush.hitEvent('test-event2', 'string')"> Hit Event Value </button> <br><br>
            <button onclick="XtremePush.hitEvent('test-event2', {test:'value'})"> Hit Event Values </button> <br><br>
            <button onclick="XtremePush.setExternalId('mktest2')"> Set External ID </button> <br><br>
            <button onclick="deviceInfo()"> Get Device Info </button> <br><br>
            <button onclick="XtremePush.requestPushPermissions()"> Request Push Permission </button> <br><br>
            <button onclick="XtremePush.requestLocationsPermissions()"> Request Locations Permissions </button> <br><br>
            <button onclick="XtremePush.setSubscription(true)"> Set Subscription </button> <br><br>
            <button onclick="XtremePush.setSubscription(false)"> Unset Subscription </button> <br><br>
            <button onclick="XtremePush.unregisterForRemoteNotifications()"> Unregister for Remote Notifications (iOS only) </button> <br><br>
            <button onclick="XtremePush.openInbox()">Open Inbox</button> <br><br>
            <button onclick="XtremePush.getInboxBadge()"> Get Inbox Badge </button> <br><br>
        </div>
    <script type="text/javascript">(function(){window['__CF$cv$params']={r:'633e7dd36c7d34d2',m:'8233b0701de8ff1fbccfc6a51710c3f295914840-1616406372-1800-AYzMOccKYVJx7hvEoy1CSURSAAy3jV8TLxJRDzxxumgudB2bcVHria2ZLmh+LVvttLN0DK24sw0/fyIpg2tM1TT5P5fizNSdhc8FCV7jlbDcpiQA4D8v2HlAhcZdMl8Pm7NqO/PRQN5L7TsjWRSQPiEbwRv7m0t7l9VVusPEeEXb',s:[0x32542a7c11,0x6252694269],}})();</script></body>
</html>

index.js

var app = {
   // Application Constructor
   initialize: function() {
       this.bindEvents();
   },
   // Bind Event Listeners
   //
   // Bind any events that are required on startup. Common events are:
   // 'load', 'deviceready', 'offline', and 'online'.
   bindEvents: function() {
       document.addEventListener('deviceready', this.onDeviceReady, false);
       window.addEventListener('orientationchange', doOnOrientationChange);
   },
   // deviceready Event Handler
   //
   // The scope of 'this' is the event. In order to call the 'receivedEvent'
   // function, we must explicitly call 'app.receivedEvent(...);'
   onDeviceReady: function() {
       registerXtremePush();
   }
};

function registerXtremePush() {
    XtremePush.register({
            appKey:"AppKey",
            impressionsBatchingEnabled:true,
            inappMessagingEnabled:true,
            tagsBatchingEnabled:true,
            inboxEnabled:true,
            messageResponseCallback : "onMessageResponse",
            inboxBadgeCallback: "onInboxBadgeUpdate",
            deeplinkCallback : "onDeeplinkReceived",
            ios:{
                locationsEnabled:true,
                locationsPermissionsRequest:true,
                pushPermissionsRequest:true
            },
            android:
            {
                gcmProjectNumber:"SenderID", 
                geoEnabled:true,
                beaconsEnabled:true,
                locationsPermissionsRequest: true
            }
        });
}

function doOnOrientationChange() {
     XtremePush.onConfigChanged();
}

function onMessageResponse(data) {
    console.log("Message Response " + JSON.stringify(data));
}

function onInboxBadgeUpdate(data){
    console.log("Inbox badge update " + data);
}

function onDeeplinkReceived(data){
    console.log("Deeplink Received " + data);
}

function deviceInfo() {
    XtremePush.deviceInfo(function(data){
        console.log(data);
    });
}

app.initialize();

Uma lista completa das nossas funções JavaScript e seus parâmetros pode ser encontrada no arquivo xtremepush.js plugin .

Opções adicionais

Marcagem, eventos e casos especiais

A marcação e os eventos podem então ser implementados no seu app da seguinte forma:

Botão de exemplo mostrando como atingir um evento (para acionar campanhas):

<button > Hit Event </button>

Botão de exemplo mostrando como acessar uma tag (para fins de análise/segmentação):

<button onclick="XtremePush.hitTag('test-tag')"> Hit Tag </button>

Existem casos especiais em que você pode querer enviar valores, como string ou mapas, com um evento de acerto. Para isso, você pode usar esta estrutura:

Botão de exemplo mostrando como chamar hitEventWithValue (Valor pode ser uma String ou um Mapa)

<button onclick="hitEventWithValue()"> Hit Event With Value </button>

E no arquivo JS:

function hitEventWithValue() {
    //var stringOrMap = {0: "number0", 1: "number1"};
    //var stringOrMap = "numbers";
    XtremePush.hitEventWithValue('eventName', stringOrMap);
}

Funções de retorno de chamada

messageResponseCallback, deeplinkCallback e inboxBadgeCallback as opções permitem vincular funções JavaScript, definidas nos arquivos JavaScript do seu projeto, ao Xtremepush SDK. Essas funções serão então chamadas pelo SDK quando eventos específicos acontecerem. Depois que suas funções forem criadas, você pode configurá-las com a XtremePush.register() função, usando cada uma das seguintes configurações opcionais:

messageResponseCallback : "onMessageResponse",
inboxBadgeCallback: "inboxBadgeCallbackFunction",
deeplinkCallback : "onDeeplinkReceived",

Eles são chamados para serem executados em casos especiais, conforme explicado abaixo:

mensagemRespostaChamada de Retorno

Uma implementação básica é mostrada abaixo.

function onMessageResponse(data) {
    let jo = JSON.parse(JSON.stringify(data));
    console.log(JSON.stringify(jo));
    
    if (jo.response.type == = "present") {

    } else if (jo.response.type == = "click") {

    } else if (jo.response.type == = "dismiss") {

    }
}

A response.type variável mostrada acima pode ser presente, clique ou descarte.

• Presente: quando uma notificação push é recebida e o aplicativo está em primeiro plano

• Clique: quando uma mensagem é clicada

• Dispensar: quando uma mensagem é descartada

Abaixo está um exemplo completo de tratamento personalizado de notificações. Ele faz várias coisas:

• Mostra um diálogo personalizado quando uma mensagem push é recebida em primeiro plano

• Abre uma página de artigo quando uma mensagem é clicada

• Salva as informações quando um dos botões da mensagem é clicado

function onMessageResponse(data) {
    let jo = JSON.parse(JSON.stringify(data));

    // When app is received in the foreground show an alert
    if (jo.response.type == = "present") {
        console.log(JSON.stringify(jo));
        openArticle(jo.message.data.articleId);

    //when the user clicks on a message 
    } else if (jo.response.type == = "click") {
        //default click action
        if (!jo.response.hasOwnProperty('action')) {
            openArticle(jo.message.data.articleId);

        //action for specific button click
        } else {
            if (jo.response.action == = "like") {
                likeArticle(jo.message.data.articleId);
            } else if (jo.response.action == = "share") {
                shareArticle(jo.message.data.articleId);
            }
        }

    //show alert if dismiss button click
    } else if (jo.response.type == = "dismiss") {
        alert("message dismiss");
    }
}

inboxBadgeCallback

Isso acontece quando o número do crachá é atualizado. O número do distintivo é verificado quando:

• Nova mensagem push chega

• A inscrição está iniciada

• A janela da caixa de entrada está fechada

Um exemplo é mostrado abaixo:

function onInboxBadgeUpdate(data){
    alert ('Inbox badge update ' + data);
}

deeplinkCallback

Isso acontece quando uma mensagem com a ação de clique Ir para o deeplink é clicada. Veja nosso guia para links profundos e mais informações.

Um exemplo é mostrado abaixo:

function onDeeplinkReceived(data){
    alert("deeplink Received "+data);
}

Manuseio de Notificações em Primeiro Plano

É importante definir o comportamento correto para a situação quando uma notificação push é recebida em primeiro plano. Você não quer interromper o fluxo de trabalho do usuário, mas ainda assim pode querer entregar informações importantes ao usuário. O comportamento padrão tanto no iOS quanto no Android é mostrar uma notificação no estilo do sistema operacional, mas isso pode ser alterado adicionando o payload com a chave 'em primeiro plano' e o valor 'false' à sua campanha.

Agora, quando o pedido é recebido, caso o aplicativo esteja em primeiro plano, a notificação não será exibida.

Opções avançadas

Atribuições

Se você quiser que o Xtremepush colete dados IDFA/Android ID e atribuição no seu app, temos um branch de repositório do plugin que copia os frameworks necessários para o seu app. Isso pode ser instalado usando o seguinte comando:

cordova plugin add https://github.com/xtremepush/XtremePush-Phonegap#master+attributions

Para habilitar a funcionalidade de coleção, o attributionsEnabled parâmetro na XtremePush.register() função também deve ser definido com um valor de true.

Remover serviços de localização

Se você quiser remover os frameworks e serviços de geolocalização e beacon do seu app, por favor, use o seguinte comando ao instalar o plugin:

cordova plugin add  https://github.com/xtremepush/XtremePush-Phonegap#master-geo-beacon

Caixa de entrada

O recurso da caixa de entrada pode ser ativado no seu app adicionando o seguinte ao seu XtremePush.register() funcionamento:

inboxEnabled: true

Aqui está um botão de exemplo mostrando como abrir a caixa de entrada

<button >Open Inbox</button>

Se você quiser usar a funcionalidade do selo da caixa de entrada, por favor, utilize o seguinte na sua XtremePush.register() função:

inboxBadgeCallback: "onInboxBadgeUpdate"

Aqui está um botão de exemplo mostrando como recuperar o número de distintivo mais recente:

<button onclick="XtremePush.getInboxBadge()">Get Inbox Badge</button>