Pular para o conteúdo principal

Quickstart KMP (iOS)

Passo 1 - Abrindo o projeto KMP no Xcode​

  1. Acesse a pasta iosApp criada pelo KMP.
  2. Abra o arquivo iosApp.xcodeproj no Xcode.

Janela do Finder no macOS mostrando o conteúdo da pasta 'iosApp'. O nome da pasta 'iosApp' no topo da janela está destacado em vermelho, e o arquivo iosApp.xcodeproj está destacado em vermelho com uma seta apontando para ele.

Passo 2 - Editando o arquivo Info.plist usando o editor visual do Xcode​

Todas as permissões do seu aplicativo iOS estão listadas na seção Custom iOS Target Properties do Info.plist.

  1. No navegador de arquivos (painel esquerdo), selecione o seu projeto no topo da árvore.
  2. Selecione o target do aplicativo em TARGETS.
  3. Acesse a aba Info.

Janela do Xcode mostrando a aba Info do target. Três áreas estão destacadas em vermelho: o nome do projeto no topo do navegador à esquerda, o target do aplicativo na seção TARGETS e a aba Info no topo do editor. À direita, a seção Custom iOS Target Properties lista as chaves de permissão e seus respectivos valores.

Passo 3 - Adicionando permissões​

Nota: As mensagens de descrição são exibidas quando o aplicativo solicita ao usuário permissão para usar um serviço. Certifique-se de adicionar uma mensagem que seja significativa para os seus usuários.

Habilitar os Serviços de Localização​

Para obter os resultados de alcance dos beacons, a tecnologia Group Link requer a autorização de localização Always. Ao implementar os serviços de localização no seu app, a Apple exige que as seguintes chaves sejam adicionadas ao seu arquivo Info.plist:

  • NSLocationWhenInUseUsageDescription
  • NSLocationAlwaysAndWhenInUseUsageDescription

Exemplo de Descrição: A localização ajuda a garantir leituras mais precisas e alertas corretos sobre o consumo de água. Isso permite que o app entregue dados de consumo da sua residência.

Configuração das permissões de localização no editor do Info.plist.

Habilitar os Serviços de Bluetooth​

Desde o iOS 13, os apps são obrigados a adicionar a chave de permissão Bluetooth ao arquivo Info.plist.

  • NSBluetoothAlwaysUsageDescription

Exemplo de Descrição: Para garantir a qualidade das leituras de consumo, o app precisa acessar o Bluetooth, que ajuda a coletar os dados de forma mais precisa.

Configuração da permissão de Bluetooth no editor do Info.plist.

Apps compatíveis com iOS 12 e inferiores​

Se o seu aplicativo puder ser executado em versões mais antigas do iOS (iOS 12 e inferiores), você precisará colocar a chave Bluetooth Peripheral dentro do seu arquivo Info.plist:

  • NSBluetoothPeripheralUsageDescription

Exemplo de Descrição: Para garantir a qualidade das leituras de consumo, o app precisa acessar o Bluetooth, que ajuda a coletar os dados de forma mais precisa.

Configuração da permissão Bluetooth Peripheral no editor do Info.plist.

Habilitar a funcionalidade de tarefas em segundo plano​

Para habilitar as tarefas em segundo plano no seu aplicativo, você precisa inserir a seguinte chave no seu arquivo Info.plist:

  • BGTaskSchedulerPermittedIdentifiers

Abra a chave criada, Permitted background task scheduler identifiers, e insira o nosso identificador:

  • com.grouplinknetwork.bgtask

Configuração dos identificadores permitidos do agendador de tarefas em segundo plano no editor do Info.plist.

Passo 4 - Permissões e Capabilities de Assinatura​

  1. Selecione o target do aplicativo em TARGETS.
  2. Acesse a aba Signing & Capabilities.
  3. Clique no botão + Capability para adicionar as seguintes capabilities:

Aba Signing & Capabilities do target do aplicativo no Xcode. Três áreas estão destacadas em vermelho: o target do aplicativo na seção 'TARGETS', a aba 'Signing & Capabilities' no topo e o botão '+ Capability'.

Habilitar o Acesso às Informações de WiFi​

O seu aplicativo deve ser capaz de acessar as informações da rede WiFi para que a tecnologia Group Link funcione corretamente. Para isso, você deve adicionar a seguinte capability:

  • Access WiFi Information

Capability Access WiFi Information adicionada na aba Signing & Capabilities.

Habilitar os Background Modes Necessários​

O seu aplicativo deve ser capaz de executar em background modes para que a tecnologia Group Link funcione corretamente. Para isso, você deve adicionar a seguinte capability:

  • Background Modes

Capability Background Modes adicionada na aba Signing & Capabilities.

Selecione as seguintes autorizações na lista:

  1. Location updates
  2. Uses Bluetooth LE accessories
  3. Acts as a Bluetooth LE accessory
  4. Background fetch
  5. Background processing

Os cinco Background Modes obrigatórios selecionados na aba Signing & Capabilities.

Passo 5 - Instalando o pacote Group Link​

Adicionando um novo pacote ao seu projeto​

  1. No Xcode, localize o painel à esquerda e clique no seu PROJECT.
  2. No topo da janela aberta, clique na aba Package Dependencies.
  3. A lista de pacotes utilizados no projeto será exibida.
  4. Clique no botão + localizado na parte inferior esquerda dessa lista para adicionar um novo pacote.

Tela do Xcode com três áreas destacadas em vermelho: a seção PROJECT da barra lateral esquerda, a aba Package Dependencies no topo do editor e o botão '+' na parte inferior da lista de pacotes. A lista de Packages está vazia (0 itens), exibindo a mensagem "Add packages here".

Buscando o pacote pela URL do GitHub​

  1. No campo de busca, no canto superior direito da janela, cole a URL do repositório: https://github.com/Group-Link-Mobile/grouplink-package
  2. Em alguns instantes, o resultado grouplink-package aparecerá na lista.
  3. Clique no grouplink-package para selecioná-lo.
  4. Altere a Dependency Rule para Up to Next Minor Version e adicione a versão 6.2.0.
  5. Clique em Add Package para adicionar o grouplink-package ao projeto.

⚠️ Atenção: Na Dependency Rule, não utilize as opções Up to Next Major Version, Branch, Exact Version, Range of Versions ou Commit. A configuração correta é Up to Next Minor Version → 6.2.0. Essa configuração garante que você sempre utilizará uma versão compatível do SDK publicada pelo Group Link.

Janela de adição do Swift Package Manager (SPM) no Xcode com a busca retornando o repositório grouplink-package. A URL aparece destacada em vermelho no campo de busca no canto superior direito, e o grouplink-package está destacado em vermelho na lista de resultados. Os campos da Dependency Rule definidos como Up to Next Minor Version com o valor '6.2.0' estão destacados em amarelo.

Escolhendo os produtos do pacote​

O Xcode irá resolver o pacote e abrir a janela Choose Package Products for grouplink-package.git.

  1. Verifique se o pacote GroupLink está na lista.
  2. Na coluna Add to Target, confirme que ele está associado ao seu aplicativo.
  3. Clique em Add Package para confirmar a adição do pacote.

Modal de seleção do grouplink-package no Xcode, listando o produto GroupLink do tipo Library a ser adicionado ao target. O botão Add Package, no canto inferior direito do diálogo, está destacado em vermelho.

Verificando a instalação​

Após a conclusão, você retornará à aba Package Dependencies. Lá, confirme que está tudo correto:

  • A lista deve exibir agora o pacote GroupLink-iOS.
  • O pacote GroupLink-iOS aparece com:
    • Location: https://github.com/Group-Link-Mobile/grouplink-package
    • Dependency Rule: Up to Next Minor Version
    • Value: 6.2.0

Aba Package Dependencies do projeto no Xcode, mostrando 1 item na lista de Packages. O pacote GroupLink aparece com a location apontando para o repositório do GitHub e a Dependency Rule definida como Up to Next Minor Version 6.2.0.

Passo 6 - Iniciando o Group Link SDK​

Para inicializar o SDK, você precisa passar o seu Token de autenticação (fornecido pela Group Link).

  • Importe a biblioteca do SDK.
  • No método start, especifique o seu Token de autenticação (fornecido pela Group Link) no parâmetro withToken.
  • Chame os métodos startBluetooth e startLocation para solicitar as permissões de Bluetooth e Localização.
import SwiftUI

import GroupLink // <---- Importing the Group Link SDK

@main
struct iOSApp: App {
    init() {
        // 1 - Initializing the SDK Group Link
        GroupLinkSDK.start(withToken: "YOUR_GROUP_LINK_TOKEN")
        
        // 2 - Requesting Bluetooth permission
        GroupLinkSDK.startBluetooth()
        
        // 2 - Requesting Location Permission
        GroupLinkSDK.startLocation()
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Agora que o Group Link SDK para iOS está implementado e os recursos nativos estão configurados, o seu app KMP está pronto para interagir com o nosso ecossistema!