Desperte com a API AlarmKit

Olá! Meu nome é Anton. Sou engineer da equipe System Experience. Nesta sessão, vou mostrar o AlarmKit, um framework que permite criar alarmes no seu app. Neste vídeo, vou explicar a experiência que pode ser criada com o AlarmKit. Depois, mostrarei como obter a autorização do seu app para usar esse framework, como criar um alarme e como gerenciar seu ciclo de vida. Vou começar pela experiência. Um alarme é um alerta para eventos que ocorrem em um horário fixo e pré-determinado. Tem como base um cronograma ou contagem regressiva. Quando é acionado, o alerta interrompe o modo silencioso e o foco atual.

No alerta, as pessoas veem o título personalizado do alarme e o nome do seu app. Há a opção de parar o alerta ou adiá-lo usando um botão de soneca opcional.

Um alarme também pode ter um botão personalizado cuja ação é definida por um App Intent.

Os alarmes funcionam em outras experiências do sistema, como o modo repouso e no Apple Watch, se emparelhado com o iPhone quando o alarme toca.

Os alarmes aceitam uma interface de contagem regressiva usando Atividades ao Vivo fornecidas pelo app. Ela pode ser exibida na Tela de Bloqueio, na Dynamic Island e no modo repouso.

As pessoas optam por ativar o alarme para cada app em seu dispositivo. Sabendo o que é um alarme, vamos falar sobre o que você precisa fazer para permitir que as pessoas autorizem que seu app agende alarmes.

Antes que seu app agende alarmes, as pessoas precisarão consentir, dando autorização. Você pode solicitar a autorização manualmente, ou ela será solicitada automaticamente ao criar seu primeiro alarme. As pessoas podem alterar o status da autorização no app Ajustes quando quiserem. Configurar a autorização é simples: basta adicionar a chave NSAlarmKitUsageDescription ao arquivo Info.plist do app, explicando o motivo do uso de alarmes. Forneça uma explicação breve e clara de como seu app usará os alarmes, para ajudar as pessoas a tomarem a melhor decisão. Para solicitar autorização manualmente, use a API AlarmManager requestAuthorization. Se a escolha ainda não tiver sido feita, será exibida uma mensagem com a descrição do uso.

Verifique o status da autorização antes de agendar um alarme consultando a propriedade authorizationState na classe AlarmManager.

Se o status for indefinido, posso solicitar a autorização manualmente. Se autorizado, posso seguir com o agendamento do alarme. Se negado, é importante deixar claro na interface do app que o alarme não será agendado. Agora que você tem familiaridade com a configuração de autorização para alarmes, vamos criar um alarme. As principais partes para criar um alarme são: duração da contagem regressiva, cronograma com data específica ou padrão de recorrência, configuração da aparência, ações personalizadas e o som associado.

Primeiro, a duração da contagem regressiva. Um alarme pode ter um intervalo de contagem regressiva antes e depois do alerta. Quando um alarme é agendado, a interface de contagem regressiva aparece durante o tempo definido antes do alerta. Quando o tempo de pré-alerta termina, o alarme toca e exibe a interface de alerta, personalizada conforme sua configuração.

Se o alarme for adiado, a interface da contagem regressiva reaparece durante o intervalo pós-alerta.

Quando esse intervalo termina, o alarme toca novamente e pode ser adiado ou dispensado.

Neste exemplo, vou configurar um timer com duração de pré-alerta de 10 minutos. Quando o alarme tocar e for repetido, ele vai contar 5 minutos depois do alerta e tocar de novo. Ao criar um alarme, você também pode definir um cronograma, que pode ser fixo ou relativo.

Um cronograma fixo especifica uma data futura única em que o alarme tocará. O cronograma é absoluto, continuando o mesmo quando o fuso horário é alterado. Neste exemplo, configurei para um alarme tocar durante a WWDC. Crio os componentes de data para 9 de junho às 9h41. Em seguida, uso esses componentes para criar a data.

Passo a data para o cronograma do alarme usando o inicializador fixo. Também posso especificar um cronograma relativo para o alarme. Isso inclui o horário do dia e um padrão opcional de recorrência semanal. O cronograma relativo considera mudanças de fuso horário.

Neste exemplo, vou configurar o alarme para tocar às 7h toda segunda, quarta e sexta-feira. Defino a hora e o minuto para o horário e especifico a ocorrência diária.

Agora que você sabe agendar alarmes, vamos passar para a personalização da aparência do alarme. Há vários elementos que você pode personalizar. Quero criar um timer de cozinha no meu app e personalizar como o alerta aparece quando toca. Começo criando o botão de alerta usando a estrutura AlarmButton. Ela permite especificar o texto, textColor e systemImage do botão.

Uso isso para definir o botão de parar, que terá o título “Dispensar” e a cor do texto branca.

Também incluirá um SF Symbol, que será usado quando o alerta for exibido na Dynamic Island.

Posso criar a apresentação do alerta e definir o título do alarme, indicando que a comida está pronta. Também incluo o botão de parar que criei. Vou criar os atributos do alarme. Pense nisso como as informações necessárias para mostrar a apresentação do seu alarme. Vou passar a apresentação do alerta que criei no parâmetro de apresentação. Por fim, vou criar a configuração do alarme. É como se fossem todas as partes necessárias para agendar um alarme, incluindo a duração da contagem regressiva, o cronograma e os atributos. Vou passar os atributos para a configuração do alarme.

Configurei a apresentação do alerta do meu alarme com um botão de desligar.

Se o alarme só precisa exibir um alerta, isso basta para configurar a aparência. Se você quiser que seu alarme exiba uma interface de contagem regressiva, há mais alguns passos a seguir. Vou mostrar esses passos para o meu alarme de cozinha. Vou adicionar um botão de repetição para iniciar uma nova contagem regressiva.

Crio o botão de repetição usando a struct AlarmButton e defino o título como "Repetição". Vou especificar a cor do texto como branca e um ícone de repetição, que aparecerá quando o alarme for exibido na Dynamic Island.

Ao criar a apresentação do alerta, também incluo meu botão Repetir.

O parâmetro behavior do secondaryButton especifica se o botão secundário altera o alarme para o estado de contagem regressiva, como repetir um timer ou adiar um alarme, ou se executa uma ação personalizada. Ao tocar o botão de repetição, o alerta deve mudar para a contagem regressiva neste caso. Especifico isso definindo secondaryButtonBehavior como countdown. Vou criar os atributos do alarme com a apresentação do alerta e, em seguida, a AlarmConfiguration com esses atributos. Adicionei um botão de repetição ao alerta que iniciará a contagem regressiva. Preciso implementar uma Atividade ao Vivo para mostrar a interface da contagem regressiva. Se o alarme aceita a funcionalidade de contagem regressiva, seu app é obrigado a implementá-la usando uma Atividade ao Vivo. Farei isso em seguida. Vou criar uma contagem regressiva para avisar quando a comida estiver pronta. Ela aparecerá na Tela de Bloqueio, na Dynamic Island e em repouso.

Se você sabe criar uma Atividade ao Vivo, sabe como criar uma interface personalizada para a contagem regressiva. Você precisará adicionar a Atividade ao Vivo de contagem regressiva à extensão de widget do app.

Se você não tiver uma, não se preocupe. Assista ao vídeo da WWDC23 chamado “Conhecer o ActivityKit”. Configure uma ActivityConfiguration e especifique AlarmAttributes com seu tipo de metadados.

Neste caso, posso configurar uma ActivityConfiguration e especificar que ela usará atributos de alarme e metadados CookingData. Vou me concentrar na Tela de Bloqueio. A contagem regressiva pode estar em estado countdown ou paused. Vou fornecer uma visualização correspondente para cada estado.

Para fazer isso, verifico o modo atual do alarme no objeto de contexto e exibo a visualização apropriada.

Primeiro, configuro o estado countdown e forneço a countdownView. Em seguida, configuro o estado paused e forneço a pausedView. Vou configurar as expandedRegions da aparência da Dynamic Island. Elas contêm o título do alarme, a contagem regressiva e os botões. Depois, configuro as visualizações compacta e mínima da Dynamic Island. Elas vão conter a contagem regressiva do alarme e um ícone. Configurei minha contagem regressiva básica de Atividade ao Vivo e vou adicionar um ícone para indicar como a comida é preparada. Posso fornecer essas informações adicionais nos metadados do alarme. CookingData é uma struct em conformidade com o protocolo AlarmMetadata. Defino um enum de strings para especificar o método de preparo, incluindo fritar e grelhar como opções. Crio uma propriedade para armazenar meu método de preparo. Agora posso usar os metadados dos dados de preparo. Ao agendar o alarme no app, crio o objeto CookingData e especifico fritar como o método de preparo. Depois, incluo esses metadados personalizados ao criar os atributos do alarme.

Na minha Atividade ao Vivo, acesso o método de preparo nos metadados personalizados usando os atributos de contexto.

Posso usar o método de preparo para criar um ícone. Quando a contagem regressiva for renderizada, ela terá o ícone de fritar que gerei usando o método de preparo nos metadados de preparo. Ele é usado na Tela de Bloqueio e na Dynamic Island.

Configurei minha contagem regressiva de alarme usando uma Atividade ao Vivo. Criei um ícone para minha contagem regressiva usando metadados do alarme.

Se o alarme for compatível com a funcionalidade de contagem regressiva, o sistema exibirá uma interface de contagem regressiva. Em alguns casos, a Atividade ao Vivo não pode ser exibida, por exemplo, após reinicializações do dispositivo e antes do primeiro desbloqueio. Nesse caso, você pode personalizar a apresentação da contagem regressiva pelo sistema. Vou configurar a apresentação do sistema para a contagem regressiva do alarme de preparo. Vou definir o botão de pausa usando a struct AlarmButton. E vou configurá-lo para ter um ícone de pausa.

Vou criar a apresentação da contagem regressiva, definir o título para indicar que a comida está sendo preparada e incluir o botão Pausar.

Defini a apresentação da contagem regressiva e vou incluí-la como parte dos atributos do alarme. Como o alarme aceita a funcionalidade de pausa, vou configurar a apresentação do sistema para o estado pausado da contagem regressiva de preparo. Quando a contagem regressiva for pausada, quero que seja possível retomá-la. Vou definir um botão Retomar usando a struct AlarmButton. E vou configurá-lo para ter um ícone Reproduzir.

Crio a apresentação pausada e defino o título como “Preparo pausado”. Também incluo o botão Retomar.

Posso adicionar a apresentação pausada aos atributos do alarme. Já configurei as apresentações do sistema para alerta, contagem regressiva e pausa. Vamos falar sobre a cor do tom. Ela é usada em todas essas apresentações e ajuda as pessoas a associar o alarme ao app. Eu a passo como parte dos atributos do alarme. Na apresentação de alerta, é usada para definir a cor de preenchimento do botão secundário.

Na Tela de Bloqueio, é usada para colorir o ícone do botão secundário, assim como o título do alarme e a contagem regressiva. Também é usada na Dynamic Island. Você já conhece a configuração da aparência do alarme, agora vamos passar para a personalização das ações. O AlarmKit permite executar seu próprio código quando alguém toca em um botão do alarme. Você pode fazer isso usando um App Intent. Forneça um App Intent personalizado para o botão de parar e o botão secundário. Vamos criar um botão secundário que executará um App Intent para abrir meu app quando for tocado. Para isso, preciso modificar a aparência do alerta. Começo criando um botão Abrir usando a struct AlarmButton. Ele se chamará "Abrir", terá uma cor de texto branco e um ícone de seta na Dynamic Island.

Ao criar a apresentação de alerta, incluirei o botão Abrir como botão secundário.

Para que esse botão execute uma ação personalizada, vou alterar o comportamento do botão secundário para custom.

O botão secundário personalizado está pronto. Vou configurar uma ação usando um App Intent para abrir o app quando o botão for tocado. Este é o App Intent que quero usar para abrir o app. Ele inclui o identificador do alarme para o qual o botão foi tocado. Ele define o sinalizador openAppWhenRun como true para indicar que quero que o app seja aberto quando o intent for executado. Uma vez que meu app é aberto, posso realizar tarefas como exibir uma visualização detalhada do alarme com aquele identificador. Vamos usar o intent que acabei de criar. Ao agendar o alarme, crio um identificador único que permite rastrear esse alarme após a criação. Crio uma instância do intent OpenInApp e passo o identificador único do alarme.

Ao criar minha configuração de alarme, incluo o intent secundário para indicar ao sistema que desejo que este intent seja executado quando o botão secundário for pressionado.

Adicionei um botão Abrir personalizado ao meu alerta, defini um App Intent para abrir meu app e indiquei ao sistema que execute esse intent quando o botão Abrir for pressionado. Vamos dedicar um momento para falar sobre como configurar o som do alarme. Se um parâmetro de som não for especificado, o alarme usará o som padrão do sistema. É possível fornecer um som personalizado para o alarme. Como o AlarmKit usa o ActivityKit para a apresentação do alarme, defina um som personalizado usando a struct AlertSound.

Você precisará especificar o nome do arquivo de som, que deve estar no pacote principal do app ou na pasta Biblioteca/Sons do contêiner de dados do app. Depois de configurar seu alarme, você poderá gerenciá-lo no sistema. Faça isso usando a classe AlarmManager. Depois de configurar o alarme, posso agendá-lo no sistema. Para isso, uso o identificador único do alarme e a configuração que criei. O identificador deve ser usado para acompanhar o alarme durante o seu ciclo de vida.

Você tem controle total sobre o ciclo de vida do alarme. Faça a transição para o estado de contagem regressiva, cancelar, parar, pausar ou retomar o alarme.

Vou deixar algumas boas práticas ao usar o AlarmKit. Alarmes são ideais para contagens regressivas com intervalo específico, como timer de cozinha, ou alertas recorrentes com cronograma, como um despertador. Eles não substituem outras notificações importantes, como alertas críticos ou notificações sensíveis ao tempo.

Busque clareza na apresentação do seu alerta. Os alertas aparecem em destaque, e você deve deixar claro para a pessoa do que se trata o alarme e quais ações ela pode realizar.

Se o alarme tiver contagem regressiva, inclua os elementos principais dessa contagem na sua Atividade ao Vivo. Isso inclui o tempo restante, um botão Dispensar e um botão Pausar ou Retomar. Você aprendeu como usar o AlarmKit para criar alarmes e gerenciar o ciclo de vida deles no sistema. Agora você pode testar isso no seu app. Use o AlarmKit para configurar alarmes para os casos de uso do seu app. Crie experiências de contagem regressiva na Tela de Bloqueio e na Dynamic Island usando Atividades ao Vivo. Adicione ações personalizadas aos alarmes usando App Intents.

Por hoje é só. Agradeço sua participação.