1. Visão geral
Neste codelab, você vai aprender a usar o Cloud Functions para Firebase para adicionar funcionalidades a um app de chat da Web com o envio de notificações para os usuários do app de chat.
Conteúdo
- Criar funções do Google Cloud Functions usando o SDK do Firebase
- Acionar o Cloud Functions com base nos eventos Auth, Cloud Storage e Cloud Firestore
- Tornar o app da Web compatível com o Firebase Cloud Messaging
Pré-requisitos
- Cartão de crédito. O Cloud Functions para Firebase requer o plano Firebase Blaze, o que significa que você precisará ativar o faturamento no seu projeto do Firebase usando um cartão de crédito.
- O ambiente de desenvolvimento integrado/editor de texto de sua escolha, como WebStorm, Atom ou Sublime.
- Um terminal para executar comandos do shell com NodeJS v9 instalado.
- Um navegador, como o Chrome.
- O exemplo de código. Confira a próxima etapa para isso.
2. Acessar o exemplo de código
Clone o repositório do GitHub (link em inglês) da linha de comando:
git clone https://github.com/firebase/friendlychat
Importar o app inicial
Usando seu ambiente de desenvolvimento integrado, abra ou importe o diretório 
cloud-functions-start do diretório de exemplo de código. Esse diretório contém o código inicial do codelab, que consiste em um app da Web do Chat totalmente funcional.
3. Criar um projeto do Firebase e configurar o app
Criar projeto
No Console do Firebase, clique em Adicionar projeto e dê o nome FriendlyChat.
Clique em Criar projeto.
Fazer upgrade para o plano Blaze
Se você quiser usar o Cloud Functions para Firebase, faça upgrade do seu projeto do Firebase para o plano de faturamento Blaze. Para isso, será preciso adicionar um cartão de crédito ou outra forma de faturamento à sua conta do Google Cloud.
Todos os projetos do Firebase, incluindo aqueles no plano Blaze, ainda têm acesso às cotas de uso sem custo financeiro do Cloud Functions. As etapas descritas neste codelab estão dentro dos limites de uso do Nível sem custo financeiro. No entanto, você vai receber pequenas cobranças (cerca de US $0,03) do Cloud Storage usadas para hospedar suas imagens de criação do Cloud Functions.
Caso você não tenha acesso a um cartão de crédito ou não se sinta à vontade para continuar com o plano Blaze, use o Pacote de emuladores do Firebase, que permite emular o Cloud Functions sem custo financeiro na sua máquina local.
Ativar o Google Auth
Para permitir que os usuários façam login no app, usaremos a autenticação do Google, que precisa estar ativada.
No console do Firebase, abra a seção Build > Autenticação > guia Método de login ou clique aqui. Em seguida, ative o provedor de login do Google e clique em Salvar. Isso permitirá que os usuários façam login no app da Web com as Contas do Google deles.
Além disso, é possível definir o nome público do seu app como Friendly Chat:
Ativar o Cloud Storage
O app usa o Cloud Storage para fazer upload de imagens. Para ativar o Cloud Storage no seu projeto do Firebase, acesse a seção Armazenamento e clique no botão Vamos começar. Siga as etapas abaixo e, para o local do Cloud Storage, haverá um valor padrão a ser usado. Depois, clique em Concluído.
Adicionar um app da Web
No console do Firebase, adicione um app da Web. Para fazer isso, acesse Configurações do projeto e role a tela para baixo até Adicionar app. Escolha a Web como a plataforma e marque a caixa para configurar o Firebase Hosting. Em seguida, registre o app e clique em Próxima para as etapas restantes. Por último, clique em Continuar no console.
4. Instalar a interface de linha de comando do Firebase
A interface de linha de comando (CLI) do Firebase permite disponibilizar o app da Web localmente e implantar esse app e o Cloud Functions.
Para instalar ou fazer upgrade da CLI, execute o seguinte comando npm:
npm -g install firebase-tools
Para verificar se a CLI foi instalada corretamente, abra um console e execute:
firebase --version
Verifique se a versão da CLI do Firebase é superior à 4.0.0 para que ela tenha todos os recursos mais recentes necessários para o Cloud Functions. Caso contrário, execute npm install -g firebase-tools para fazer upgrade, conforme mostrado acima.
Autorize a CLI do Firebase executando:
firebase login
Verifique se você está no diretório cloud-functions-start e configure a CLI do Firebase para usar seu projeto:
firebase use --add
Em seguida, selecione o ID do projeto e siga as instruções. Quando solicitado, escolha qualquer alias, como codelab.
5. Implante e execute o app da Web
Agora que você importou e configurou seu projeto, está pronto para executar o app da Web pela primeira vez. Abra uma janela do terminal, navegue até a pasta cloud-functions-start e implante o app da Web no Firebase Hosting usando:
firebase deploy --except functions
Esta é a resposta do console que você deverá ver:
i deploying database, storage, hosting
✔ database: rules ready to deploy.
i storage: checking rules for compilation errors...
✔ storage: rules file compiled successfully
i hosting: preparing ./ directory for upload...
✔ hosting: ./ folder uploaded successfully
✔ storage: rules file compiled successfully
✔ hosting: 8 files uploaded successfully
i starting release process (may take several minutes)...
✔ Deploy complete!
Project Console: https://console.firebase.google.com/project/friendlychat-1234/overview
Hosting URL: https://friendlychat-1234.firebaseapp.com
Abrir o app da Web
A última linha deve exibir o URL do Hosting. O app da Web agora deve ser exibido por esse URL, que deve estar no formato https://<project-id>.firebaseapp.com. Abra-o. A interface funcional de um app de chat vai aparecer.
Faça login no app usando o botão SIGN-IN WITH GOOGLE e adicione algumas mensagens e poste imagens:
Se você fizer login no app pela primeira vez em um novo navegador, permita as notificações quando solicitado: 
As notificações precisarão ser ativadas posteriormente.
Se você clicar acidentalmente em Bloquear, mude essa configuração clicando no botão 🔒 Seguro à esquerda do URL no Chrome Omnibar e alternando a barra ao lado de Notificações:
Agora, vamos adicionar algumas funcionalidades usando o SDK do Firebase para Cloud Functions.
6. O diretório de funções
Com o Cloud Functions, é fácil executar o código no Cloud sem precisar configurar um servidor. Vamos mostrar como criar funções que reagem a eventos do Firebase Auth, Cloud Storage e Firebase Firestore. Vamos começar com o Auth.
Ao usar o SDK do Firebase para Cloud Functions, seu código do Functions fica no diretório functions (por padrão). Seu código do Functions também é um app do Node.js e, portanto, precisa de um package.json que forneça algumas informações sobre seu app e liste as dependências.
Para facilitar, já criamos o arquivo functions/index.js onde seu código será armazenado. Fique à vontade para inspecionar esse arquivo antes de continuar.
cd functions
ls
Se você não conhece o Node.js, pode ser útil aprender mais sobre ele antes de continuar o codelab.
O arquivo package.json já lista duas dependências obrigatórias: o SDK do Firebase para Cloud Functions e o SDK Admin do Firebase. Para instalá-los localmente, acesse a pasta functions e execute:
npm install
Agora, vamos dar uma olhada no arquivo index.js:
index.js
/**
* Copyright 2017 Google Inc. All Rights Reserved.
* ...
*/
// TODO(DEVELOPER): Import the Cloud Functions for Firebase and the Firebase Admin modules here.
// TODO(DEVELOPER): Write the addWelcomeMessage Function here.
// TODO(DEVELOPER): Write the blurImages Function here.
// TODO(DEVELOPER): Write the sendNotification Function here.
Vamos importar os módulos necessários e escrever três funções no lugar dos TODOs. Vamos começar importando os módulos Node necessários.
7. Importe os módulos do Cloud Functions e do Firebase Admin
Dois módulos serão necessários durante este codelab: o firebase-functions permite gravar acionadores e registros do Cloud Functions, enquanto o firebase-admin permite usar a plataforma do Firebase em um servidor com acesso de administrador para realizar ações como gravar no Cloud Firestore ou enviar notificações do FCM.
No arquivo index.js, substitua o primeiro TODO pelo seguinte:
index.js
/**
* Copyright 2017 Google Inc. All Rights Reserved.
* ...
*/
// Import the Firebase SDK for Google Cloud Functions.
const functions = require('firebase-functions');
// Import and initialize the Firebase Admin SDK.
const admin = require('firebase-admin');
admin.initializeApp();
// TODO(DEVELOPER): Write the addWelcomeMessage Function here.
// TODO(DEVELOPER): Write the blurImages Function here.
// TODO(DEVELOPER): Write the sendNotification Function here.
O SDK Admin do Firebase pode ser configurado automaticamente quando implantado em um ambiente do Cloud Functions ou em outros contêineres do Google Cloud Platform. Isso acontece quando chamamos admin.initializeApp() sem argumentos.
Agora, vamos adicionar uma função que é executada quando um usuário faz login pela primeira vez no app de chat e adicionar uma mensagem de chat para dar as boas-vindas ao usuário.
8. Dê boas-vindas aos novos usuários
Estrutura de mensagens do chat
As mensagens postadas no feed de chat do FriendlyChat são armazenadas no Cloud Firestore. Vamos dar uma olhada na estrutura de dados que usamos para uma mensagem. Para fazer isso, poste uma nova mensagem no chat que diz "Hello World":
Ele deve aparecer assim:
No Console do Firebase, clique em Banco de dados do Firestore na seção Build. Você verá a coleção de mensagens e um documento contendo a mensagem que você escreveu:
Como você pode notar, as mensagens de chat são armazenadas no Cloud Firestore como um documento com os atributos name, profilePicUrl, text e timestamp adicionados à coleção messages.
Como adicionar mensagens de boas-vindas
A primeira função do Cloud adiciona uma mensagem de boas-vindas para novos usuários ao chat. Para isso, podemos usar o gatilho functions.auth().onCreate, que executa a função sempre que um usuário faz login pela primeira vez no app Firebase. Adicione a função addWelcomeMessages ao arquivo index.js:
index.js
// Adds a message that welcomes new users into the chat.
exports.addWelcomeMessages = functions.auth.user().onCreate(async (user) => {
functions.logger.log('A new user signed in for the first time.');
const fullName = user.displayName || 'Anonymous';
// Saves the new welcome message into the database
// which then displays it in the FriendlyChat clients.
await admin.firestore().collection('messages').add({
name: 'Firebase Bot',
profilePicUrl: '/images/firebase-logo.png', // Firebase logo
text: `${fullName} signed in for the first time! Welcome!`,
timestamp: admin.firestore.FieldValue.serverTimestamp(),
});
functions.logger.log('Welcome message written to database.');
});
Adicionar essa função ao objeto exports especial é a maneira de o Node tornar a função acessível fora do arquivo atual e é necessária para o Cloud Functions.
Na função acima, adicionamos uma nova mensagem de boas-vindas postada por "Firebase Bot" à lista de mensagens de chat. Para isso, usamos o método add na coleção messages do Cloud Firestore, em que as mensagens são armazenadas.
Como essa é uma operação assíncrona, precisamos retornar a Promise indicando quando a gravação do Cloud Firestore terminou, para que as funções do Cloud não sejam executadas muito cedo.
Implantar o Cloud Functions
O Cloud Functions só vai ficar ativo depois de ser implantado. Para fazer isso, execute este comando na linha de comando:
firebase deploy --only functions
Esta é a resposta do console que você deverá ver:
i deploying functions
i functions: ensuring necessary APIs are enabled...
⚠ functions: missing necessary APIs. Enabling now...
i env: ensuring necessary APIs are enabled...
⚠ env: missing necessary APIs. Enabling now...
i functions: waiting for APIs to activate...
i env: waiting for APIs to activate...
✔ env: all necessary APIs are enabled
✔ functions: all necessary APIs are enabled
i functions: preparing functions directory for uploading...
i functions: packaged functions (X.XX KB) for uploading
✔ functions: functions folder uploaded successfully
i starting release process (may take several minutes)...
i functions: creating function addWelcomeMessages...
✔ functions[addWelcomeMessages]: Successful create operation.
✔ functions: all functions deployed successfully!
✔ Deploy complete!
Project Console: https://console.firebase.google.com/project/friendlypchat-1234/overview
Testar a função
Depois que a função for implantada, você precisará ter um usuário que faça login pela primeira vez.
- Abra seu app no navegador usando o URL de hospedagem (no formato
https://<project-id>.firebaseapp.com). - Com um novo usuário, faça login pela primeira vez no app usando o botão Fazer login.
- Se você já tiver feito login no app, abra o Firebase Console Authentication e exclua sua conta da lista de usuários. Em seguida, faça login novamente.
- Depois de fazer login, uma mensagem de boas-vindas aparece automaticamente:
9. Moderação de imagens
Os usuários podem enviar todo tipo de imagem no chat, e é sempre importante moderar imagens ofensivas, especialmente em plataformas sociais públicas. No FriendlyChat, as imagens que são publicadas no chat são armazenadas no Google Cloud Storage.
Com o Cloud Functions, é possível detectar novos uploads de imagens usando o gatilho functions.storage().onFinalize. Ele será executado sempre que um novo arquivo for carregado ou modificado no Cloud Storage.
Para moderar imagens, passaremos pelo seguinte processo:
- Verifique se a imagem está sinalizada como "Para adultos" ou "Violenta" usando a API Cloud Vision.
- Se a imagem foi sinalizada, faça o download dela na instância do Functions em execução.
- Desfoque a imagem usando o ImageMagick.
- Faça upload da imagem borrada no Cloud Storage.
Ative a API Cloud Vision
Como usaremos a API Google Cloud Vision nessa função, você precisa ativar a API no seu projeto do Firebase. Acesse este link, selecione seu projeto do Firebase e ative a API:
Instalar dependências
Para moderar imagens, usaremos a biblioteca de cliente do Google Cloud Vision para Node.js, @google-cloud/vision, a fim de executar imagens por meio da API Cloud Vision para detectar imagens inapropriadas.
Para instalar este pacote no app Cloud Functions, execute o comando npm install --save a seguir. Faça isso no diretório functions.
npm install --save @google-cloud/vision@2.4.0
Isso vai instalar o pacote localmente e adicioná-lo como uma dependência declarada no arquivo package.json.
Importar e configurar dependências
Para importar as dependências que foram instaladas e alguns módulos principais do Node.js (path, os e fs) necessários nesta seção, adicione as seguintes linhas à parte de cima do arquivo index.js:
index.js
const Vision = require('@google-cloud/vision');
const vision = new Vision.ImageAnnotatorClient();
const {promisify} = require('util');
const exec = promisify(require('child_process').exec);
const path = require('path');
const os = require('os');
const fs = require('fs');
Como a função será executada em um ambiente do Google Cloud, não é necessário configurar as bibliotecas do Cloud Storage e do Cloud Vision: elas serão configuradas automaticamente para usar o projeto.
Como detectar imagens inadequadas
Você vai usar o gatilho functions.storage.onChange do Cloud Functions, que executa seu código assim que um arquivo ou uma pasta é criado ou modificado em um bucket do Cloud Storage. Adicione a função blurOffensiveImages ao arquivo index.js:
index.js
// Checks if uploaded images are flagged as Adult or Violence and if so blurs them.
exports.blurOffensiveImages = functions.runWith({memory: '2GB'}).storage.object().onFinalize(
async (object) => {
const imageUri = `gs://${object.bucket}/${object.name}`;
// Check the image content using the Cloud Vision API.
const batchAnnotateImagesResponse = await vision.safeSearchDetection(imageUri);
const safeSearchResult = batchAnnotateImagesResponse[0].safeSearchAnnotation;
const Likelihood = Vision.protos.google.cloud.vision.v1.Likelihood;
if (Likelihood[safeSearchResult.adult] >= Likelihood.LIKELY ||
Likelihood[safeSearchResult.violence] >= Likelihood.LIKELY) {
functions.logger.log('The image', object.name, 'has been detected as inappropriate.');
return blurImage(object.name);
}
functions.logger.log('The image', object.name, 'has been detected as OK.');
});
Adicionamos algumas configurações da instância do Cloud Functions que vão executar a função. Com .runWith({memory: '2GB'}), estamos solicitando que a instância tenha 2 GB de memória em vez do padrão, porque essa função consome muita memória.
Quando a função é acionada, a imagem é executada pela API Cloud Vision para detectar se ela está sinalizada como adulta ou violenta. Se a imagem for detectada como inadequada com base nesses critérios, ela será desfocada, o que é feito na função blurImage, como veremos a seguir.
Como desfocar a imagem
Adicione a seguinte função blurImage ao arquivo index.js:
index.js
// Blurs the given image located in the given bucket using ImageMagick.
async function blurImage(filePath) {
const tempLocalFile = path.join(os.tmpdir(), path.basename(filePath));
const messageId = filePath.split(path.sep)[1];
const bucket = admin.storage().bucket();
// Download file from bucket.
await bucket.file(filePath).download({destination: tempLocalFile});
functions.logger.log('Image has been downloaded to', tempLocalFile);
// Blur the image using ImageMagick.
await exec(`convert "${tempLocalFile}" -channel RGBA -blur 0x24 "${tempLocalFile}"`);
functions.logger.log('Image has been blurred');
// Uploading the Blurred image back into the bucket.
await bucket.upload(tempLocalFile, {destination: filePath});
functions.logger.log('Blurred image has been uploaded to', filePath);
// Deleting the local file to free up disk space.
fs.unlinkSync(tempLocalFile);
functions.logger.log('Deleted local file.');
// Indicate that the message has been moderated.
await admin.firestore().collection('messages').doc(messageId).update({moderated: true});
functions.logger.log('Marked the image as moderated in the database.');
}
Na função acima, é feito o download do binário da imagem do Cloud Storage. A imagem é desfocada usando a ferramenta convert do ImageMagick, e essa versão é reenviada ao bucket do Storage. Em seguida, excluímos o arquivo na instância do Cloud Functions para liberar espaço em disco. Fazemos isso porque a mesma instância do Cloud Functions pode ser reutilizada e, se os arquivos não forem limpos, ela pode ficar sem espaço em disco. Por fim, adicionamos um booleano à mensagem do chat indicando que a imagem foi moderada, o que aciona uma atualização da mensagem no cliente.
Implantar a função
A função só vai ficar ativa depois de ser implantada. Na linha de comando, execute firebase deploy --only functions:
firebase deploy --only functions
Esta é a resposta do console que você deverá ver:
i deploying functions
i functions: ensuring necessary APIs are enabled...
✔ functions: all necessary APIs are enabled
i functions: preparing functions directory for uploading...
i functions: packaged functions (X.XX KB) for uploading
✔ functions: functions folder uploaded successfully
i starting release process (may take several minutes)...
i functions: updating function addWelcomeMessages...
i functions: creating function blurOffensiveImages...
✔ functions[addWelcomeMessages]: Successful update operation.
✔ functions[blurOffensiveImages]: Successful create operation.
✔ functions: all functions deployed successfully!
✔ Deploy complete!
Project Console: https://console.firebase.google.com/project/friendlychat-1234/overview
Testar a função
Depois que a função for implantada, faça o seguinte:
- Abra seu app no navegador usando o URL de hospedagem (no formato
https://<project-id>.firebaseapp.com). - Depois de fazer login no app, faça upload de uma imagem:
- Escolha sua melhor imagem ofensiva para enviar (ou use este zumbi comendo carne) e, depois de alguns instantes, a postagem será atualizada com uma versão desfocada da imagem:
10. Notificações de novas mensagens
Nesta seção, você vai adicionar uma função do Cloud que envia notificações aos participantes do chat quando uma nova mensagem é postada.
Ao usar o Firebase Cloud Messaging (FCM), envie notificações de maneira confiável a usuários em várias plataformas. Para enviar uma notificação a um usuário, você precisa do token do dispositivo do FCM. O app de chat da Web que estamos usando já coleta tokens do dispositivo dos usuários quando eles abrem o app pela primeira vez em um novo navegador ou dispositivo. Esses tokens são armazenados na coleção fcmTokens do Cloud Firestore.
Se você quiser saber como receber tokens de dispositivo do FCM em um app da Web, consulte o Firebase Web Codelab.
Enviar notificações
Para detectar quando novas mensagens são postadas, você vai usar o gatilho functions.firestore.document().onCreate do Cloud Functions, que executa seu código quando um novo objeto é criado em um determinado caminho do Cloud Firestore. Adicione a função sendNotifications ao arquivo index.js:
index.js
// Sends a notifications to all users when a new message is posted.
exports.sendNotifications = functions.firestore.document('messages/{messageId}').onCreate(
async (snapshot) => {
// Notification details.
const text = snapshot.data().text;
const payload = {
notification: {
title: `${snapshot.data().name} posted ${text ? 'a message' : 'an image'}`,
body: text ? (text.length <= 100 ? text : text.substring(0, 97) + '...') : '',
icon: snapshot.data().profilePicUrl || '/images/profile_placeholder.png',
click_action: `https://${process.env.GCLOUD_PROJECT}.firebaseapp.com`,
}
};
// Get the list of device tokens.
const allTokens = await admin.firestore().collection('fcmTokens').get();
const tokens = [];
allTokens.forEach((tokenDoc) => {
tokens.push(tokenDoc.id);
});
if (tokens.length > 0) {
// Send notifications to all tokens.
const response = await admin.messaging().sendToDevice(tokens, payload);
await cleanupTokens(response, tokens);
functions.logger.log('Notifications have been sent and tokens cleaned up.');
}
});
Na função acima, estamos reunindo os tokens de dispositivo de todos os usuários do banco de dados do Cloud Firestore e enviando uma notificação para cada um deles usando a função admin.messaging().sendToDevice.
Limpar os tokens
Por fim, vamos remover os tokens que não são mais válidos. Isso acontece quando o token que recebemos do usuário não é mais usado pelo navegador ou dispositivo. Isso acontece, por exemplo, se o usuário revogou a permissão de notificações da sessão do navegador. Para fazer isso, adicione a seguinte função cleanupTokens ao arquivo index.js:
index.js
// Cleans up the tokens that are no longer valid.
function cleanupTokens(response, tokens) {
// For each notification we check if there was an error.
const tokensDelete = [];
response.results.forEach((result, index) => {
const error = result.error;
if (error) {
functions.logger.error('Failure sending notification to', tokens[index], error);
// Cleanup the tokens that are not registered anymore.
if (error.code === 'messaging/invalid-registration-token' ||
error.code === 'messaging/registration-token-not-registered') {
const deleteTask = admin.firestore().collection('fcmTokens').doc(tokens[index]).delete();
tokensDelete.push(deleteTask);
}
}
});
return Promise.all(tokensDelete);
}
Implantar a função
A função só vai ficar ativa depois de ser implantada. Para implantá-la, execute este comando na linha de comando:
firebase deploy --only functions
Esta é a resposta do console que você deverá ver:
i deploying functions
i functions: ensuring necessary APIs are enabled...
✔ functions: all necessary APIs are enabled
i functions: preparing functions directory for uploading...
i functions: packaged functions (X.XX KB) for uploading
✔ functions: functions folder uploaded successfully
i starting release process (may take several minutes)...
i functions: updating function addWelcomeMessages...
i functions: updating function blurOffensiveImages...
i functions: creating function sendNotifications...
✔ functions[addWelcomeMessages]: Successful update operation.
✔ functions[blurOffensiveImages]: Successful updating operation.
✔ functions[sendNotifications]: Successful create operation.
✔ functions: all functions deployed successfully!
✔ Deploy complete!
Project Console: https://console.firebase.google.com/project/friendlychat-1234/overview
teste a função
- Depois que a função for implantada, abra seu app no navegador usando o URL de hospedagem (na forma de
https://<project-id>.firebaseapp.com). - Se você fizer login no app pela primeira vez, permita as notificações quando solicitado:
- Feche a guia do app de chat ou mostre uma guia diferente: as notificações só vão aparecer se o app estiver em segundo plano. Se quiser aprender a receber mensagens enquanto o app está em primeiro plano, consulte nossa documentação.
- Usando um navegador diferente ou uma janela anônima, faça login no app e poste uma mensagem. Você verá uma notificação exibida pelo primeiro navegador:
.
11. Parabéns!
Você usou o SDK do Firebase para o Cloud Functions e adicionou componentes do servidor a um app de chat.
O que vimos
- Criar Funções do Cloud usando o SDK do Firebase para o Cloud Functions
- Acionar o Cloud Functions com base nos eventos Auth, Cloud Storage e Cloud Firestore
- Tornar o app da Web compatível com o Firebase Cloud Messaging
- Implantar o Cloud Functions usando a CLI do Firebase.
Próximas etapas
- Saiba mais sobre outros tipos de gatilhos do Cloud Functions.
- Use o Firebase e o Cloud Functions com seu app.
Saiba mais
- firebase.google.com/docs/functions
- firebase.google.com (link em inglês)