Codelab para iOS do Cloud Firestore

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

1. Visão Geral

Metas

Neste codelab, você criará um aplicativo de recomendação de restaurantes com suporte do Firestore no iOS no Swift. Você vai aprender como:

  1. Ler e gravar dados no Firestore de um aplicativo iOS
  2. Ouça as alterações nos dados do Firestore em tempo real
  3. Use o Firebase Authentication e as regras de segurança para proteger os dados do Firestore
  4. Escrever consultas complexas do Firestore

Pré-requisitos

Antes de iniciar este codelab, certifique-se de ter instalado:

  • Xcode versão 13.0 (ou superior)
  • CocoaPods 1.11.0 (ou superior)

2. Crie um projeto de console do Firebase

Adicionar o Firebase ao projeto

  1. Acesse o console do Firebase .
  2. Selecione Criar novo projeto e nomeie seu projeto como "Firestore iOS Codelab".

3. Obtenha o Projeto de Amostra

Baixe o Código

Comece clonando o projeto de amostra e executando a pod update no diretório do projeto:

git clone https://github.com/firebase/friendlyeats-ios
cd friendlyeats-ios
pod update

Abra FriendlyEats.xcworkspace no Xcode e execute-o (Cmd+R). O aplicativo deve compilar corretamente e travar imediatamente na inicialização, pois está faltando um arquivo GoogleService-Info.plist . Corrigiremos isso na próxima etapa.

Configurar o Firebase

Siga a documentação para criar um novo projeto do Firestore. Depois de obter seu projeto, baixe o arquivo GoogleService-Info.plist do seu projeto do console do Firebase e arraste-o para a raiz do projeto Xcode. Execute o projeto novamente para garantir que o aplicativo seja configurado corretamente e não falhe mais na inicialização. Após o login, você deverá ver uma tela em branco como no exemplo abaixo. Se você não conseguir fazer login, verifique se ativou o método de login por e-mail/senha no console do Firebase em Autenticação.

d5225270159c040b.png

4. Gravar dados no Firestore

Nesta seção, gravaremos alguns dados no Firestore para que possamos preencher a IU do aplicativo. Isso pode ser feito manualmente por meio do console do Firebase , mas faremos isso no próprio aplicativo para demonstrar uma gravação básica do Firestore.

O objeto de modelo principal em nosso aplicativo é um restaurante. Os dados do Firestore são divididos em documentos, coleções e subcoleções. Armazenaremos cada restaurante como um documento em uma coleção de nível superior chamada restaurants . Se quiser saber mais sobre o modelo de dados do Firestore, leia sobre documentos e coleções na documentação .

Antes de podermos adicionar dados ao Firestore, precisamos obter uma referência à coleção de restaurantes. Adicione o seguinte ao loop for interno no método RestaurantsTableViewController.didTapPopulateButton(_:) .

let collection = Firestore.firestore().collection("restaurants")

Agora que temos uma referência de coleção, podemos escrever alguns dados. Adicione o seguinte logo após a última linha de código que adicionamos:

let collection = Firestore.firestore().collection("restaurants")

// ====== ADD THIS ======
let restaurant = Restaurant(
  name: name,
  category: category,
  city: city,
  price: price,
  ratingCount: 0,
  averageRating: 0
)

collection.addDocument(data: restaurant.dictionary)

O código acima adiciona um novo documento à coleção de restaurantes. Os dados do documento vêm de um dicionário, que obtemos de uma estrutura Restaurant.

Estamos quase lá. Antes de podermos gravar documentos no Firestore, precisamos abrir as regras de segurança do Firestore e descrever quais partes do nosso banco de dados devem ser graváveis ​​por quais usuários. Por enquanto, permitiremos que apenas usuários autenticados leiam e gravem em todo o banco de dados. Isso é um pouco permissivo demais para um aplicativo de produção, mas durante o processo de criação do aplicativo, queremos algo relaxado o suficiente para que não tenhamos problemas de autenticação constantemente durante a experimentação. No final deste codelab, falaremos sobre como fortalecer suas regras de segurança e limitar a possibilidade de leituras e gravações não intencionais.

Na guia Regras do console do Firebase, adicione as seguintes regras e clique em Publicar .

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      //
      // WARNING: These rules are insecure! We will replace them with
      // more secure rules later in the codelab
      //
      allow read, write: if request.auth != null;
    }
  }
}

Discutiremos as regras de segurança em detalhes mais tarde, mas se você estiver com pressa, dê uma olhada na documentação das regras de segurança .

Execute o aplicativo e faça login. Em seguida, toque no botão " Preencher " no canto superior esquerdo, que criará um lote de documentos do restaurante, embora você ainda não o veja no aplicativo.

Em seguida, navegue até a guia de dados do Firestore no console do Firebase. Agora você deve ver novas entradas na coleção de restaurantes:

Captura de tela 06-07-2017 às 12h45.38.png

Parabéns, você acabou de gravar dados no Firestore a partir de um aplicativo iOS! Na próxima seção, você aprenderá a recuperar dados do Firestore e exibi-los no aplicativo.

5. Exibir dados do Firestore

Nesta seção, você aprenderá como recuperar dados do Firestore e exibi-los no aplicativo. As duas etapas principais são criar uma consulta e adicionar um ouvinte de instantâneo. Este ouvinte será notificado de todos os dados existentes que correspondem à consulta e receberá atualizações em tempo real.

Primeiro, vamos construir a consulta que servirá à lista padrão e não filtrada de restaurantes. Dê uma olhada na implementação de RestaurantsTableViewController.baseQuery() :

return Firestore.firestore().collection("restaurants").limit(to: 50)

Essa consulta recupera até 50 restaurantes da coleção de nível superior denominada "restaurantes". Agora que temos uma consulta, precisamos anexar um listener de snapshot para carregar dados do Firestore em nosso aplicativo. Adicione o seguinte código ao método RestaurantsTableViewController.observeQuery() logo após a chamada para stopObserving() .

listener = query.addSnapshotListener { [unowned self] (snapshot, error) in
  guard let snapshot = snapshot else {
    print("Error fetching snapshot results: \(error!)")
    return
  }
  let models = snapshot.documents.map { (document) -> Restaurant in
    if let model = Restaurant(dictionary: document.data()) {
      return model
    } else {
      // Don't use fatalError here in a real app.
      fatalError("Unable to initialize type \(Restaurant.self) with dictionary \(document.data())")
    }
  }
  self.restaurants = models
  self.documents = snapshot.documents

  if self.documents.count > 0 {
    self.tableView.backgroundView = nil
  } else {
    self.tableView.backgroundView = self.backgroundView
  }

  self.tableView.reloadData()
}

O código acima baixa a coleção do Firestore e a armazena em uma matriz localmente. A addSnapshotListener(_:) adiciona um ouvinte de instantâneo à consulta que atualizará o controlador de exibição sempre que os dados forem alterados no servidor. Recebemos atualizações automaticamente e não precisamos enviar manualmente as alterações. Lembre-se de que esse listener de instantâneo pode ser invocado a qualquer momento como resultado de uma alteração no lado do servidor, portanto, é importante que nosso aplicativo possa lidar com as alterações.

Depois de mapear nossos dicionários para structs (consulte Restaurant.swift ), exibir os dados é apenas uma questão de atribuir algumas propriedades de visualização. Adicione as seguintes linhas a RestaurantTableViewCell.populate(restaurant:) em RestaurantsTableViewController.swift .

nameLabel.text = restaurant.name
cityLabel.text = restaurant.city
categoryLabel.text = restaurant.category
starsView.rating = Int(restaurant.averageRating.rounded())
priceLabel.text = priceString(from: restaurant.price)

Esse método de preenchimento é chamado a partir do método tableView(_:cellForRowAtIndexPath:) da fonte de dados de exibição de tabela, que cuida do mapeamento da coleção de tipos de valor anteriores para as células de exibição de tabela individuais.

Execute o aplicativo novamente e verifique se os restaurantes que vimos anteriormente no console agora estão visíveis no simulador ou dispositivo. Se você concluiu esta seção com sucesso, seu aplicativo agora está lendo e gravando dados com o Cloud Firestore!

391c0259bf05ac25.png

6. Classificando e Filtrando Dados

Atualmente nosso aplicativo exibe uma lista de restaurantes, mas não há como o usuário filtrar com base em suas necessidades. Nesta seção, você usará a consulta avançada do Firestore para ativar a filtragem.

Aqui está um exemplo de uma consulta simples para buscar todos os restaurantes Dim Sum:

let filteredQuery = query.whereField("category", isEqualTo: "Dim Sum")

Como o próprio nome indica, o whereField(_:isEqualTo:) fará com que nossa consulta baixe apenas membros da coleção cujos campos atendam às restrições que definimos. Nesse caso, ele fará o download apenas de restaurantes cuja category seja "Dim Sum" .

Neste aplicativo, o usuário pode encadear vários filtros para criar consultas específicas, como "Pizza em San Francisco" ou "Frutos do mar em Los Angeles ordenados por popularidade".

Abra RestaurantsTableViewController.swift e adicione o seguinte bloco de código ao meio de query(withCategory:city:price:sortBy:) :

if let category = category, !category.isEmpty {
  filtered = filtered.whereField("category", isEqualTo: category)
}

if let city = city, !city.isEmpty {
  filtered = filtered.whereField("city", isEqualTo: city)
}

if let price = price {
  filtered = filtered.whereField("price", isEqualTo: price)
}

if let sortBy = sortBy, !sortBy.isEmpty {
  filtered = filtered.order(by: sortBy)
}

O snippet acima adiciona várias cláusulas whereField e order para criar uma única consulta composta com base na entrada do usuário. Agora, nossa consulta retornará apenas restaurantes que atendam aos requisitos do usuário.

Execute seu projeto e verifique se você pode filtrar por preço, cidade e categoria (certifique-se de digitar os nomes da categoria e da cidade exatamente). Durante o teste, você pode ver erros em seus logs que se parecem com isso:

Error fetching snapshot results: Error Domain=io.grpc Code=9 
"The query requires an index. You can create it here: https://console.firebase.google.com/project/testapp-5d356/database/firestore/indexes?create_index=..." 
UserInfo={NSLocalizedDescription=The query requires an index. You can create it here: https://console.firebase.google.com/project/project-id/database/firestore/indexes?create_index=...}

Isso ocorre porque o Firestore exige índices para a maioria das consultas compostas. A exigência de índices nas consultas mantém o Firestore rápido em escala. Abrir o link da mensagem de erro abrirá automaticamente a IU de criação de índice no console do Firebase com os parâmetros corretos preenchidos. Para saber mais sobre índices no Firestore, visite a documentação .

7. Gravando dados em uma transação

Nesta seção, adicionaremos a capacidade de os usuários enviarem avaliações a restaurantes. Até agora, todas as nossas gravações foram atômicas e relativamente simples. Se algum deles apresentar erro, provavelmente solicitaremos ao usuário que tente novamente ou tente novamente automaticamente.

Para adicionar uma classificação a um restaurante, precisamos coordenar várias leituras e gravações. Primeiro, a avaliação em si deve ser enviada e, em seguida, a contagem de classificação do restaurante e a classificação média precisam ser atualizadas. Se um deles falhar, mas não o outro, ficaremos em um estado inconsistente, onde os dados em uma parte do nosso banco de dados não correspondem aos dados em outra.

Felizmente, o Firestore oferece funcionalidade de transação que nos permite realizar várias leituras e gravações em uma única operação atômica, garantindo que nossos dados permaneçam consistentes.

Adicione o seguinte código abaixo de todas as declarações let em RestaurantDetailViewController.reviewController(_:didSubmitFormWithReview:) .

let firestore = Firestore.firestore()
firestore.runTransaction({ (transaction, errorPointer) -> Any? in

  // Read data from Firestore inside the transaction, so we don't accidentally
  // update using stale client data. Error if we're unable to read here.
  let restaurantSnapshot: DocumentSnapshot
  do {
    try restaurantSnapshot = transaction.getDocument(reference)
  } catch let error as NSError {
    errorPointer?.pointee = error
    return nil
  }

  // Error if the restaurant data in Firestore has somehow changed or is malformed.
  guard let data = restaurantSnapshot.data(),
        let restaurant = Restaurant(dictionary: data) else {

    let error = NSError(domain: "FireEatsErrorDomain", code: 0, userInfo: [
      NSLocalizedDescriptionKey: "Unable to write to restaurant at Firestore path: \(reference.path)"
    ])
    errorPointer?.pointee = error
    return nil
  }

  // Update the restaurant's rating and rating count and post the new review at the 
  // same time.
  let newAverage = (Float(restaurant.ratingCount) * restaurant.averageRating + Float(review.rating))
      / Float(restaurant.ratingCount + 1)

  transaction.setData(review.dictionary, forDocument: newReviewReference)
  transaction.updateData([
    "numRatings": restaurant.ratingCount + 1,
    "avgRating": newAverage
  ], forDocument: reference)
  return nil
}) { (object, error) in
  if let error = error {
    print(error)
  } else {
    // Pop the review controller on success
    if self.navigationController?.topViewController?.isKind(of: NewReviewViewController.self) ?? false {
      self.navigationController?.popViewController(animated: true)
    }
  }
}

Dentro do bloco de atualização, todas as operações que fizermos usando o objeto de transação serão tratadas como uma única atualização atômica pelo Firestore. Se a atualização falhar no servidor, o Firestore tentará automaticamente algumas vezes. Isso significa que nossa condição de erro provavelmente é um único erro que ocorre repetidamente, por exemplo, se o dispositivo estiver completamente offline ou o usuário não estiver autorizado a gravar no caminho em que está tentando gravar.

8. Regras de segurança

Os usuários do nosso aplicativo não devem poder ler e gravar todos os dados em nosso banco de dados. Por exemplo, todos devem poder ver as avaliações de um restaurante, mas apenas um usuário autenticado deve ter permissão para postar uma avaliação. Não é suficiente escrever um bom código no cliente, precisamos especificar nosso modelo de segurança de dados no backend para ser completamente seguro. Nesta seção, aprenderemos a usar as regras de segurança do Firebase para proteger nossos dados.

Primeiro, vamos dar uma olhada mais profunda nas regras de segurança que escrevemos no início do codelab. Abra o console do Firebase e navegue até Banco de dados > Regras na guia Firestore .

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      // Only authenticated users can read or write data
      allow read, write: if request.auth != null;
    }
  }
}

A variável de request nas regras acima é uma variável global disponível em todas as regras, e a condicional que adicionamos garante que a solicitação seja autenticada antes de permitir que os usuários façam qualquer coisa. Isso impede que usuários não autenticados usem a API Firestore para fazer alterações não autorizadas em seus dados. Este é um bom começo, mas podemos usar as regras do Firestore para fazer coisas muito mais poderosas.

Vamos restringir as gravações de avaliações para que o ID do usuário da avaliação corresponda ao ID do usuário autenticado. Isso garante que os usuários não possam se passar por outros e deixar avaliações fraudulentas. Substitua suas regras de segurança pelo seguinte:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /restaurants/{any}/ratings/{rating} {
      // Users can only write ratings with their user ID
      allow read;
      allow write: if request.auth != null 
                   && request.auth.uid == request.resource.data.userId;
    }
  
    match /restaurants/{any} {
      // Only authenticated users can read or write data
      allow read, write: if request.auth != null;
    }
  }
}

A primeira declaração de correspondência corresponde às ratings nomeadas da subcoleção de qualquer documento pertencente à coleção de restaurants . A condicional allow write impede que qualquer revisão seja enviada se o ID do usuário da revisão não corresponder ao do usuário. A segunda declaração de correspondência permite que qualquer usuário autenticado leia e grave restaurantes no banco de dados.

Isso funciona muito bem para nossas avaliações, pois usamos regras de segurança para declarar explicitamente a garantia implícita que escrevemos em nosso aplicativo anteriormente – que os usuários só podem escrever suas próprias avaliações. Se adicionássemos uma função de edição ou exclusão para comentários, esse mesmo conjunto de regras também impediria que os usuários modificassem ou excluíssem comentários de outros usuários. Mas as regras do Firestore também podem ser usadas de maneira mais granular para limitar gravações em campos individuais dentro de documentos, em vez de documentos inteiros. Podemos usar isso para permitir que os usuários atualizem apenas as classificações, a classificação média e o número de classificações de um restaurante, eliminando a possibilidade de um usuário mal-intencionado alterar o nome ou a localização de um restaurante.

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /restaurants/{restaurant} {
      match /ratings/{rating} {
        allow read: if request.auth != null;
        allow write: if request.auth != null 
                     && request.auth.uid == request.resource.data.userId;
      }
    
      allow read: if request.auth != null;
      allow create: if request.auth != null;
      allow update: if request.auth != null
                    && request.resource.data.name == resource.data.name
                    && request.resource.data.city == resource.data.city
                    && request.resource.data.price == resource.data.price
                    && request.resource.data.category == resource.data.category;
    }
  }
}

Aqui dividimos nossa permissão de gravação em criar e atualizar para que possamos ser mais específicos sobre quais operações devem ser permitidas. Qualquer usuário pode gravar restaurantes no banco de dados, preservando a funcionalidade do botão Populate que criamos no início do codelab, mas uma vez que um restaurante é escrito, seu nome, localização, preço e categoria não podem ser alterados. Mais especificamente, a última regra exige que qualquer operação de atualização do restaurante mantenha o mesmo nome, cidade, preço e categoria dos campos já existentes no banco de dados.

Para saber mais sobre o que você pode fazer com as regras de segurança, consulte a documentação .

9. Conclusão

Neste codelab, você aprendeu a fazer leituras e gravações básicas e avançadas com o Firestore, bem como proteger o acesso a dados com regras de segurança. Você pode encontrar a solução completa no codelab-complete .

Para saber mais sobre o Firestore, visite os seguintes recursos: