Salvar dados

Antes de começar

Para usar o Firebase Realtime Database, você precisa criar um projeto do Firebase e adicionar os pacotes do SDK para Unity do Firebase ao projeto do Unity.

Configuração:

Pré-requisitos

Android

  • Unity 5.0 ou posterior
  • Android NDK versão 10d ou posterior

iOS

  • Unity 5.0 ou posterior
  • Xcode 8.0 ou posterior

Se você ainda não tem um projeto do Unity, faça o download de um dos nossos exemplos de guia de início rápido e teste um recurso específico do Firebase. Nesse caso, anote o identificador do pacote nas configurações do projeto. Ele será necessário na próxima etapa.

Configurar seu app no Console do Firebase

Para adicionar o Firebase ao seu app, você precisa de um projeto e de um arquivo de configuração do Firebase.

Para criar um projeto do Firebase:

  1. Vá para o Console do Firebase.

  2. Clique em Adicionar projeto e selecione ou insira um Nome do projeto.

    • Se você tiver um projeto do Google associado ao seu aplicativo, selecione o projeto no menu suspenso Nome do projeto.
    • Se você não tiver um projeto do Google existente, insira um novo Nome do projeto.
  3. (Opcional) Edite o código do projeto.

    O Firebase atribui automaticamente um código exclusivo ao seu projeto do Firebase. Ele é exibido em serviços do Firebase visíveis publicamente, por exemplo:

    • URL padrão do banco de dados: your-project-id.firebaseio.com
    • subdomínio de hospedagem padrão: your-project-id.firebaseapp.com
  4. Siga as demais etapas de configuração e clique em Criar projeto ou Adicionar Firebase, se estiver usando um projeto existente do Google.

O Firebase provisiona recursos automaticamente para seu projeto da plataforma. O processo normalmente leva alguns minutos. Quando o processo for concluído, você será direcionado para a página de visão geral do seu projeto no Console do Firebase.

Android

  1. Clique em Adicionar o Firebase ao app para Android e siga as etapas de configuração. Se você estiver importando um projeto do Google, isso pode ocorrer automaticamente. Basta fazer o download do arquivo de configuração.
  2. Quando solicitado, digite o nome do pacote do seu app. É importante inserir o nome do pacote usado pelo seu aplicativo, mas essa configuração só pode ser feita quando você adiciona um app ao seu projeto do Firebase.
  3. Durante o processo, você fará o download de um arquivo google-services.json. É possível fazer o download dele novamente a qualquer momento.
  4. Depois de adicionar o código de inicialização, execute seu aplicativo para enviar ao Console do Firebase a confirmação de que você instalou o Firebase com sucesso.

iOS

  1. Clique em Adicionar o Firebase ao app para iOS e siga as etapas de configuração. Se você estiver importando um projeto do Google, isso pode ocorrer automaticamente. Basta fazer o download do arquivo de configuração.
  2. Quando solicitado, digite o código do pacote do app. É importante inserir essa informação ao adicionar um app ao projeto do Firebase.
  3. Durante o processo, você fará o download de um arquivo GoogleService-Info.plist. Você pode fazer o download desse arquivo novamente a qualquer momento.
  4. Depois de adicionar o código de inicialização, execute seu aplicativo para enviar ao Console do Firebase a confirmação de que você instalou o Firebase com sucesso.
  5. Arraste o arquivo GoogleService-Info.plist, transferido por download, do Console do Firebase para qualquer pasta no projeto do Unity.

Adicionar o SDK para Unity do Firebase ao app

  1. Faça o download do SDK para Unity do Firebase.
  2. Selecione o item de menu Recursos > Importar pacote > Pacote personalizado.
  3. Importe FirebaseDatabase.unitypackage do diretório que corresponde à versão do Unity que você usa:
    • Unity 5.x e versões anteriores usam o .NET Framework 3.x. Portanto, é necessário importar o pacote dotnet3/FirebaseDatabase.unitypackage .
    • O Unity 2017.x e versões mais recentes permitem o uso do .NET Framework 4.x. Caso seu projeto esteja configurado para usar .NET 4.x, importe o pacote dotnet4/FirebaseDatabase.unitypackage .
  4. Quando a janela Importar pacote do Unity for exibida, clique no botão Importar.

Inicializar o SDK

O SDK para Unity do Firebase no Android requer a plataforma Google Play Services, que precisa estar atualizada antes que o SDK possa ser usado. O código a seguir precisa ser adicionado no início do seu aplicativo para verificar e, como opção, atualizar o Google Play Services para a versão exigida pelo SDK para Unity do Firebase antes de chamar outros métodos no SDK.

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(task => {
  var dependencyStatus = task.Result;
  if (dependencyStatus == Firebase.DependencyStatus.Available) {
    // Create and hold a reference to your FirebaseApp, i.e.
    //   app = Firebase.FirebaseApp.DefaultInstance;
    // where app is a Firebase.FirebaseApp property of your application class.

    // Set a flag here indicating that Firebase is ready to use by your
    // application.
  } else {
    UnityEngine.Debug.LogError(System.String.Format(
      "Could not resolve all Firebase dependencies: {0}", dependencyStatus));
    // Firebase Unity SDK is not safe to use here.
  }
});

Criar o aplicativo

Android

  1. Selecione a opção de menu Arquivo > Criar configurações.
  2. Selecione Android na lista Plataforma.
  3. Clique em Alterar plataforma para selecionar Android como a plataforma de destino.
  4. No canto inferior direito da barra de status do Unity, espere o ícone de carregamento parar.
  5. Clique em Criar e executar.

iOS

  1. Selecione a opção de menu Arquivo > Criar configurações.
  2. Selecione iOS na lista Plataforma.
  3. Clique em Alterar plataforma para selecionar iOS como a plataforma de destino.
  4. No canto inferior direito da barra de status do Unity, espere o ícone de carregamento parar.
  5. Clique em Criar e executar.

Salvar dados

Há cinco métodos para escrever dados no Firebase Realtime Database:

Método Usos comuns
SetValueAsync() Escreva ou substitua dados em um caminho definido, como users/<user-id>/<username>.
SetRawJsonValueAsync() Escreva ou substitua dados com JSON bruto, como users/<user-id>/<username>.
Push() Adicione a uma lista de dados. Toda vez que você chama Push(), o Firebase gera uma chave exclusiva que também pode ser usada como um identificador exclusivo como, por exemplo, user-scores/<user-id>/<unique-score-id>.
UpdateChildrenAsync() Atualize algumas das chaves de um caminho definido sem substituir todos os dados.
RunTransaction() Atualize dados complexos que possam ser corrompidos por atualizações simultâneas.

Receber um DatabaseReference

Para gravar dados no Database, você precisa de uma instância de DatabaseReference:

using Firebase;
using Firebase.Database;
using Firebase.Unity.Editor;

public class MyScript: MonoBehaviour {
  void Start() {
    // Set up the Editor before calling into the realtime database.
    FirebaseApp.DefaultInstance.SetEditorDatabaseUrl("https://YOUR-FIREBASE-APP.firebaseio.com/");

    // Get the root reference location of the database.
    DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference;
  }
}

Gravar, atualizar ou excluir dados em uma referência

Operações básicas de gravação

Em operações básicas de gravação, use SetValueAsync() para salvar dados em uma referência específica e substitua os dados existentes no caminho. Você pode usar este método para transmitir tipos que correspondem aos tipos de JSON disponíveis abaixo:

  • string
  • long
  • double
  • bool
  • Dictionary<string, Object>
  • List<Object>

Se você usar um objeto do tipo C#, poderá utilizar o JsonUtility.ToJson() integrado para converter o objeto em JSON bruto e chamar SetRawJsonValueAsync(). Por exemplo, é possível que você tenha uma classe de usuário como a descrita a seguir:

public class User {
    public string username;
    public string email;

    public User() {
    }

    public User(string username, string email) {
        this.username = username;
        this.email = email;
    }
}

Você pode adicionar um usuário com SetRawJsonValueAsync() da seguinte forma:

private void writeNewUser(string userId, string name, string email) {
    User user = new User(name, email);
    string json = JsonUtility.ToJson(user);

    mDatabaseRef.Child("users").Child(userId).SetRawJsonValueAsync(json);
}

O uso de SetValueAsync() ou SetRawJsonValueAsync() desta maneira substitui os dados no local especificado, incluindo os nodes filhos. No entanto, ainda é possível atualizar um node filho sem reescrever todo o objeto. Para permitir que os usuários atualizem os próprios perfis, atualize o nome de usuário deles desta forma:

mDatabaseRef.Child("users").Child(userId).Child("username").SetValueAsync(name);

Anexar a uma lista de dados

Use o método Push() para anexar dados a uma lista em aplicativos de vários usuários. O método Push() gera uma chave exclusiva sempre que um novo node filho for adicionado a uma referência específica do Firebase. Ao usar essas chaves geradas automaticamente para cada novo elemento da lista, vários clientes podem adicionar filhos no mesmo local simultaneamente sem criar conflitos de gravação. A chave exclusiva gerada por Push() é baseada em um timestamp. Portanto, os itens da lista são organizados automaticamente em ordem cronológica.

Use a referência aos novos dados retornados pelo método Push() para receber o valor da chave filha gerada automaticamente ou para definir os dados da chave filha. Chamar a Key em uma referência Push() retorna o valor da chave gerada automaticamente.

Atualizar campos específicos

Para gravar filhos específicos de um node simultaneamente sem substituir outros nodes filhos, use o método UpdateChildrenAsync().

Ao chamar UpdateChildrenAsync(), atualize valores de filhos de nível inferior especificando um caminho para a chave. Se os dados estiverem armazenados em vários locais para aprimorar a escalabilidade, atualize todas as instâncias usando a distribuição de dados. Por exemplo, um jogo pode ter uma classe LeaderboardEntry como esta:

public class LeaderboardEntry {
    public string uid;
    public int score = 0;

    public LeaderboardEntry() {
    }

    public LeaderboardEntry(string uid, int score) {
        this.uid = uid;
        this.score = score;
    }

    public Dictionary&ltstring, Object&gt ToDictionary() {
        Dictionary&ltstring, Object&gt result = new Dictionary&ltstring, Object&gt();
        result["uid"] = uid;
        result["score"] = score;

        return result;
    }
}

Para criar uma LeaderboardEntry e atualizá-la simultaneamente no feed de pontuação recente e na lista de pontuação do usuário, o jogo usa o seguinte código:

private void WriteNewScore(string userId, int score) {
    // Create new entry at /user-scores/$userid/$scoreid and at
    // /leaderboard/$scoreid simultaneously
    string key = mDatabase.Child("scores").Push().Key;
    LeaderBoardEntry entry = new LeaderBoardEntry(userId, score);
    Dictionary&ltstring, Object&gt entryValues = entry.ToDictionary();

    Dictionary&ltstring, Object&gt childUpdates = new Dictionary&ltstring, Object&gt();
    childUpdates["/scores/" + key] = entryValues;
    childUpdates["/user-scores/" + userId + "/" + key] = entryValues;

    mDatabase.UpdateChildrenAsync(childUpdates);
}

Este exemplo usa Push() para criar uma entrada no node que contém entradas para todos os usuários em /scores/$key e para recuperar simultaneamente a chave com Key. Desta forma, a chave pode ser usada para criar uma segunda entrada nas pontuações do usuário em /user-scores/$userid/$key.

Com esses caminhos, você faz atualizações simultâneas em vários locais da árvore JSON com uma única chamada ao UpdateChildrenAsync() e cria a nova entrada nos dois locais. Atualizações simultâneas realizadas dessa maneira são atômicas: ou todas funcionam ou todas falham.

Excluir dados

A maneira mais simples de excluí-los é chamar RemoveValue() em uma referência ao local dos dados.

Você também pode fazer a exclusão ao especificar null como o valor de outra operação de gravação, como SetValueAsync() ou UpdateChildrenAsync(). Use essa técnica com UpdateChildrenAsync() para excluir vários filhos de uma única chamada de API.

Como saber se os seus dados foram confirmados

Para saber se os seus dados foram confirmados no servidor do Firebase Realtime Database, você pode adicionar uma continuação. SetValueAsync() e UpdateChildrenAsync() retornam uma Task que permite que você saiba quando a operação foi concluída. Se, por qualquer motivo, a chamada falhar, as Tarefas IsFaulted serão verdadeiras e a propriedade Exception indicará a causa da falha.

Salvar dados como transações

Ao trabalhar com dados que podem ser corrompidos por modificações simultâneas, como contadores incrementais, use uma operação de transação. Dê a essa operação a função Func. A função de atualização Func usa o estado atual dos dados como um argumento e retorna o novo estado de acordo com as preferências de gravação. Se outro cliente fizer uma gravação no local antes que o seu novo valor seja gravado, sua função de atualização será chamada novamente com o novo valor atual e a gravação será repetida.

Por exemplo, você pode permitir que os usuários atualizem uma tabela de classificação em um jogo com as cinco pontuações mais altas:

private void AddScoreToLeaders(string email,
                               long score,
                               DatabaseReference leaderBoardRef) {

    leaderBoardRef.RunTransaction(mutableData =&gt {
      List&ltobject&gt leaders = mutableData.Value as List&ltobject>

      if (leaders == null) {
        leaders = new List&ltobject&gt();
      } else if (mutableData.ChildrenCount &gt= MaxScores) {
        long minScore = long.MaxValue;
        object minVal = null;
        foreach (var child in leaders) {
          if (!(child is Dictionary&ltstring, object&gt)) continue;
          long childScore = (long)
                      ((Dictionary&ltstring, object&gt)child)["score"];
          if (childScore &lt minScore) {
            minScore = childScore;
            minVal = child;
          }
        }
        if (minScore &gt score) {
          // The new score is lower than the existing 5 scores, abort.
          return TransactionResult.Abort();
        }

        // Remove the lowest score.
        leaders.Remove(minVal);
      }

      // Add the new high score.
      Dictionary&ltstring, object&gt newScoreMap =
                       new Dictionary&ltstring, object&gt();
      newScoreMap["score"] = score;
      newScoreMap["email"] = email;
      leaders.Add(newScoreMap);
      mutableData.Value = leaders;
      return TransactionResult.Success(mutableData);
    });
}

Usar uma transação evita que a tabela de classificação fique incorreta caso vários usuários gravem resultados ao mesmo tempo ou o cliente tenha dados desatualizados. Se a transação for rejeitada, o servidor retornará o valor atual ao cliente, que executará a transação novamente com o valor atualizado. Isso se repetirá até que a transação seja aceita ou até que muitas tentativas sejam realizadas.

Gravar dados off-line

Se um cliente perder a conexão de rede, o app continuará funcionando.

Todos os clientes conectados a um banco de dados do Firebase mantêm a própria versão interna de dados ativos. A gravação deles ocorre primeiro nessa versão local. Depois, o cliente do Firebase sincroniza esses dados com os servidores remotos e com outros de acordo com o modelo “melhor esforço".

Consequentemente, todas as gravações no banco de dados acionam eventos locais, antes de qualquer dado ser gravado no servidor, e o app continua responsivo, independentemente da conectividade ou da latência da rede.

Para que a conectividade seja restabelecida, seu app recebe o conjunto apropriado de eventos, e o cliente faz a sincronização com o estado atual do servidor, sem precisar de um código personalizado.

Próximas etapas

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.