Com a liberação da versão 2.4 do Magic xpa, vários novos recursos estão disponíveis para os desenvolvedores de soluções Android (bem como iOS). Entre estes recursos, está o Serviço de Notificação, ou ‘Push’.
O ‘Push’ é um sistema de broadcast de mensagens que pode ser ativado pelo servidor de aplicação (no caso, o Magic xpa RIA Server) a todos os clientes conectados a este servidor (no caso, os dispositivos Android executando o Magic xpa RIA Client).
No caso do Android, o ‘Push’ está baseado no Google Cloud Messaging (gcm).
Observe que este é um serviço “on-line” do Google, ou seja, somente dispositivos conectados à internet poderão receber mensagens via ‘Push’.
Outro detalhe importante é que as notificações ‘Push’ são do tipo ‘fire-and-forget’, quer dizer, não há compromisso/garantia do servidor (no caso do Android, do Google Cloud Messaging) de que ele entregará com certeza a mensagem que foi destinada a um ou mais dispositivos.
Abaixo, seguem os passos necessários para se utilizar o ‘Push’ com Android, no Magic xpa:
1.Projeto Google API
Similar ao mostrado em outro post, sobre integração com o Google Drive, o primeiro passo é criar um projeto no Google API. Se já tiver um, pode utilizá-lo.
Neste console, existe o número do projeto:
Anote a guarde este número, pois ele será necessário posteriormente. Também ative o serviço GCM for Android:
Similar também ao mostrado com a interface com o Google Drive, é necessário definir uma API Key (caso já não possua uma):
Pode-se usar tanto uma “Browser Key” como uma “Server Key”. A diferença básica entre elas é que a “Server Key” permite montar uma White-List, relacionando os IPs autorizados a enviar as mensagens via ‘Push’.
Ao final destes procedimentos, você terá duas informações essenciais: Project Number e API Key. Elas serão usadas posteriormente.
NOTA: Esta API Key precisa ser do tipo “Key for browser apps (with referers)”.
2. Client Magic xpa
Similar à quando se quer alterar os logos ou realizar algum outro tipo de customização, é necessário “compilar” um novo client Magic xpa para Android, pois o APK standard da distribuição não suporta o ‘Push’. Os passos necessários estão detalhados no Magic Community.
A) Iniciamos fazendo uma cópia da pasta “RIAModules\Android”:
B) Em seguida, criamos os arquivos “GCMBroadcastReceiver.java”, “GCMIntentService.java” e “GCMHelper.java” na pasta “RIAModules\Android_Push\Source\src”, e inserimos nele o código java necessário para trabalhar com o ‘Push’. Você pode baixar estes três arquivos deste endereço:
NOTA: ao invés de (TestApplication) como consta no exemplo do site, deve-se usar (MainApplication).
Dentro no arquivo (GCMBroadcastReceiver.java), mais ou menos na linha #59, há uma instrução:
.setContentTitle(“<título>”)
Você pode alterar este título, que é exibido quando você puxa a cortina de notificações.
C) No arquivo ‘MainApplication.java’, temos de adicionar o código:
else if (str.toLowerCase().startsWith(“gcm:”)) {
GCMHelper gcmHelper = new GCMHelper(getApplicationContext(),str.substring(4));
gcmHelper.registerGCM();
return “”;
}
antes do “else” dentro da função “userDefinedFunction”:
D) No arquivo ‘MainActivity.java’, temos de adicionar o código:
if (getIntent().getExtras() != null)
{
intentArgs = getIntent().getExtras().getString(“gcm-message”);
}
ao final do evento “onCreate”:
E) O arquivo “gcm.jar” disponível na pasta “extras\google\gcm\gcm-client\dist” do Android SDK instalado na máquina, deve ser copiado para a nossa pasta “libs”:
Também devemos copiar o arquivo “android-support-v4.jar” da pasta “extras\android\support\v4” e o arquivo “google-play-services.jar”, da pasta “extras\google\google_play_services\libproject\google-play-services_lib\libs”:
F) Precisamos também alterar o arquivo “AndroidManifest.xml” que está na pasta “RIAModules\Android_Push\Source” e adicionar as permissões:
<permission android:name=”com.magicsoftware.magicdev.permission.C2D_MESSAGE” android:protectionLevel=”signature” />
<uses-permission android:name=”com.magicsoftware.magicdev.permission.C2D_MESSAGE” />
<uses-permission android:name=”com.google.android.c2dm.permission.RECEIVE” />
<uses-permission android:name=”android.permission.GET_ACCOUNTS” />
<uses-permission android:name=”android.permission.WAKE_LOCK” />
após a tag “uses-sdk”:
G) Ainda no arquivo “AndroidManifest.xml”, precisamos adicionar as diretrizes:
<receiver android:name=”com.google.android.gcm.GCMBroadcastReceiver” android:permission=”com.google.android.c2dm.permission.SEND” >
<intent-filter>
<action android:name=”com.google.android.c2dm.intent.RECEIVE” />
<action android:name=”com.google.android.c2dm.intent.REGISTRATION” />
<category android:name=”com.magicsoftware.magicdev” />
</intent-filter>
</receiver>
<service android:name=”.GCMIntentService” />
dentro da tag “application”:
H) Realizadas estas alterações, basta compilar o novo APK (como explicado neste outro post):
Com estes passos, nós temos agora um novo client Magic xpa que suporta o ‘Push’, bem como um ‘project number’ e ‘api key’ para o envio das mensagens.
3. Usando o ‘Push’ com o Magic xpa
Dentro da aplicação Magic xpa RIA, um fluxo específico de ações é necessário. São basicamente três ações:
A) Logo que inicia, a aplicação client precisa se registrar no sistema operacional, como uma receptora de mensagens ‘Push’. Isso é feito executando-se o comando:
ClientOSEnvGet(‘device_udf|gcm:XXXX’)
Onde “XXXX” é o número do projeto obtido no passo #1 (mais acima).
NOTA: Este comando só tem efetividade em APKs customizados com os códigos detalhados anteriormente. Com o APK standard, ele não produzirá nenhum efeito.
B) Após o registro, o sistema operacional (Android) enviará à aplicação um ID exclusivo, de uso obrigatório nos envios das mensagens ‘Push’. Para poder receber este ID, deve existir um Event Handler do tipo External Event no Main Program da aplicação. O ID virá no argumento “string” do handler, logo após o prefixo “GCM-regID:”
Este ID deve ser guardado pela aplicação, pois ele será necessário posteriormente.
NOTA: Este handler só tem efetividade em APKs customizados com os códigos detalhados anteriormente. Com o APK standard, nenhum ID será enviado à aplicação.
Além disso, a configuração da aplicação deve estar como “Exibir Notificações = SIM”:
Veja um exemplo de ID obtido:
É uma chavezinha de quase 200 caracteres
NOTA: Este trabalho de registrar a aplicação só precisa ser realizado uma vez. Após registrada, você não precisará repetir o processo para esta mesma aplicação. Lembre-se que para o Android o que diferencia uma aplicação de outra é o seu package.name
C) De posse do ID obtido no passo anterior (#B), qualquer aplicação que possua o recurso de fazer requisições HTTP, pode enviar mensagens a este dispositivo através do Android GCM, ou ‘Push’. Em aplicações Magic xpa, isso é feito através da função HTTPCall, como abaixo:
HTTPCall(‘POST’, ‘https://android.googleapis.com/gcm/send’, ‘{“registration_ids” : ‘&Trim(<dev_id>)&’,”data” : {“message” : “‘ & Trim(<msg>) & ‘”}}’ , ‘Content-Type:application/json’, ‘Authorization: key=’&Trim(<api_key>))
Onde:
<dev_id> é o ID do dispositivo ao qual se destina a mensagem (conforme o passo #B, acima). Múltiplos IDs devem ser separados por vírgula.
<msg> é o texto da mensagem a enviar.
<api_key> é a chave de acesso obtida no passo #1 (mais acima).
Exemplo:
Envio
Recebimento
Clicando na imagem, a aplicação será aberta. Os dados (mensagem) recebidos estão disponíveis à aplicação executando-se a função
ClientOSEnvGet(‘device_udf|getargs’):
É importante lembrar que a aplicação (cliente Magic xpa) precisa estar aberta (executando) no dispositivo, mesmo que escondida (em background). Do contrário, ela não receberá as notificações.
