O SDK de aplicativos para dispositivos móveis do Google Analytics para iOS facilita a implementação do Google Analytics em aplicativos com base em iOS. Este documento descreve como integrar o SDK aos seus apps.
Visão geral do SDK
Esse SDK usa um modelo de acompanhamento projetado para acompanhar os usuários em sites tradicionais e na interação com widgets em páginas da Web tradicionais. Por esse motivo, os termos usados abaixo refletem o modelo de acompanhamento convencional de sites e estão sendo associados ao acompanhamento de aplicativos para dispositivos móveis. Você precisa estar familiarizado com o acompanhamento do Analytics para entender como esse SDK funciona.
Use o SDK de acompanhamento para dispositivos móveis e acompanhe seus aplicativos para telefone com os seguintes tipos de interação do Google Analytics:
- Acompanhamento de visualização de página
- Uma visualização de página é um meio padrão para medir o volume de tráfego de um site tradicional. Como apps para dispositivos móveis não contêm páginas HTML, você precisa decidir quando e com que frequência acionar uma solicitação de visualização de página. Além disso, como as solicitações de visualização de página foram criadas para gerar relatórios sobre estruturas de diretórios, dê nomes descritivos às solicitações para aproveitar a nomenclatura do caminho da página nos relatórios de conteúdo do Google Analytics. Os nomes escolhidos são preenchidos nos relatórios do Google Analytics como caminhos de página, embora não sejam, na verdade, páginas HTML. No entanto, você pode usar isso a seu favor estruturando caminhos para fornecer mais agrupamentos às chamadas.
- Acompanhamento de eventos
- No Google Analytics, os eventos são projetados para acompanhar a interação do usuário com elementos da página da Web de maneira diferente das solicitações de visualização de página. Você pode usar o recurso Acompanhamento de eventos do Google Analytics para fazer chamadas adicionais que serão informadas na seção Acompanhamento de eventos da interface de relatórios do Analytics. Os eventos são agrupados em categorias e também podem usar rótulos por evento, o que oferece flexibilidade na geração de relatórios. Por exemplo, um app multimídia pode ter ações play/stop/pause para a categoria video e atribuir um rótulo para cada nome de vídeo. Os relatórios do Google Analytics agregariam eventos de todos os eventos marcados com a categoria vídeo. Para mais informações sobre o acompanhamento de eventos, consulte o Guia de acompanhamento de eventos
- Acompanhamento de comércio eletrônico
- Use o recurso de acompanhamento de e-commerce para acompanhar transações do carrinho de compras e compras no aplicativo.
Para acompanhar uma transação, chame o método
addTransaction
para criar uma transação geral, bem como o métodoaddItem
para cada produto no carrinho de compras. Depois de coletados, os dados podem ser visualizados na seção "Relatórios de e-commerce" da interface do Google Analytics. Para mais informações sobre o acompanhamento de comércio eletrônico, consulte o Guia de acompanhamento de comércio eletrônico. - Variáveis personalizadas
- As variáveis personalizadas são tags com pares de nome-valor que podem ser inseridas no código de acompanhamento para refinar o acompanhamento do Google Analytics. Para mais informações sobre como usar variáveis personalizadas, leia o Guia de variáveis personalizadas.
- Suporte ao NoThumb
-
O SDK para iPhone agora vem com uma versão NoThumb da biblioteca, além da versão Thumb padrão. Para usar a versão NoThumb da biblioteca, use o arquivo
libGoogleAnalytics_NoThumb.a
em vez do arquivolibGoogleAnalytics.a
.
Como começar
Requisitos
Para integrar os recursos de acompanhamento do Google Analytics ao seu app iOS, você precisará de:
- SDK do desenvolvedor iOS (requer o Xcode 3.1+ em execução no Mac OS X 10.5.3+)
- SDK do Google Analytics para apps para dispositivos móveis (iOS)
Configuração
- Abra o Xcode e crie um novo projeto do sistema operacional do iPhone.
- Arraste
GANTracker.h
elibGoogleAnalytics.a
do diretório da Biblioteca do SDK para o novo projeto. - Inclua o framework
CFNetwork
no seu projeto e vincule alibsqlite3.0.dylib
.
O SDK do Google Analytics para aplicativos para celular deve funcionar com qualquer iPhone ou iPod Touch que execute iOS 2.0 ou superior. A biblioteca é compatível com todas as versões do iOS que suportam aplicativos nativos.
O SDK inclui um aplicativo de exemplo que demonstra como o projeto deve ficar se tiver sido configurado corretamente. Você pode usá-lo como modelo para seus próprios aplicativos integrados ao Google Analytics.
Como usar o SDK
Antes de começar a usar o SDK, é necessário criar uma conta sem custo financeiro em www.google.com.br/analytics e criar uma nova propriedade da Web nessa conta usando um URL falso, mas descritivo do site (por exemplo, http://mymobileapp.mywebsite.com
). Depois de criar a propriedade, anote ou mantenha uma cópia do ID da propriedade da Web gerado para a propriedade recém-criada.
Você precisa indicar aos usuários, no próprio aplicativo ou nos Termos de Serviço, que você se reserva o direito de acompanhar e relatar anonimamente a atividade de um usuário dentro do app. O uso do SDK do Google Analytics também é regido pelos Termos de Serviço do Google Analytics, com os quais você precisa concordar ao criar uma conta.
Amostras e práticas recomendadas
Você pode encontrar exemplos de código e práticas recomendadas em code.google.com, no projeto analytics-api-samples.
Biblioteca EasyTracker
Uma biblioteca do EasyTracker está disponível. Ele oferece rastreamento de nível de aplicativo e UIViewController quase sem esforço de desenvolvimento. Você pode encontrá-lo na seção Downloads do projeto analytics-api-samples.
Iniciando o tracker
Inicie o rastreador chamando o método startTrackerWithAccountID
no Singleton do rastreador obtido por [GANTracker sharedTracker]
. Muitas vezes, é conveniente chamar esse método diretamente no método applicationDidFinishLaunching
do delegado do app. Transmita o ID da propriedade da Web, o período de envio obrigatório e o delegado opcional. Exemplo:
#import "BasicExampleAppDelegate.h" #import "GANTracker.h" // Dispatch period in seconds static const NSInteger kGANDispatchPeriodSec = 10; @implementation BasicExampleAppDelegate @synthesize window = window_; - (void)applicationDidFinishLaunching:(UIApplication *)application { // ************************************************************************** // PLEASE REPLACE WITH YOUR ACCOUNT DETAILS. // ************************************************************************** [[GANTracker sharedTracker] startTrackerWithAccountID:@"UA-0000000-1" dispatchPeriod:kGANDispatchPeriodSec delegate:nil]; NSError *error; if (![[GANTracker sharedTracker] setCustomVariableAtIndex:1 name:@"iPhone1" value:@"iv1" withError:&error]) { // Handle error here } if (![[GANTracker sharedTracker] trackEvent:@"my_category" action:@"my_action" label:@"my_label" value:-1 withError:&error]) { // Handle error here } if (![[GANTracker sharedTracker] trackPageview:@"/app_entry_point" withError:&error]) { // Handle error here } [window_ makeKeyAndVisible]; } - (void)dealloc { [[GANTracker sharedTracker] stopTracker]; [window_ release]; [super dealloc]; } @end
Acompanhamento de visualizações de página e eventos
O acompanhamento de exibições de página e eventos é simples: basta chamar trackPageView
do objeto do rastreador sempre que você quiser acionar uma visualização de página. Chame trackEvent
para gravar um evento. Para saber mais sobre visualizações de página e eventos, consulte a Visão geral do SDK acima.
Como usar variáveis personalizadas
Adicionar uma variável personalizada também é bem simples: basta usar o método setCustomVariableAtIndex
fornecido pelo SDK para dispositivos móveis. Planeje com antecedência
o qual indexa cada variável personalizada para que você não substitua nenhuma
que já tenha sido criada. Para mais informações sobre variáveis personalizadas, consulte o Guia de variáveis personalizadas. Observe que o método setCustomVariableAtIndex
não envia dados diretamente
por conta própria. Em vez disso, os dados são enviados com o próximo evento ou visualização de página acompanhado. É necessário chamar setCustomVariableAtIndex
antes de acompanhar uma visualização de página ou um evento. O escopo padrão das variáveis personalizadas é no escopo da página.
Como usar o acompanhamento de e-commerce
Existem quatro métodos para ativar o acompanhamento de e-commerce no seu aplicativo:
addTransaction
addItem
trackTransactions
clearTransactions
Chamar addTransaction
e addItem
adiciona a transação ou o item a um buffer de e-commerce interno, em que mais itens e transações podem ser adicionados. Somente ao chamar trackTransactions
, as transações e os itens são enviados ao agente e colocados na fila para serem enviados ao Google Analytics.
Para limpar o buffer, chame o método clearTransactions
.
Observação: o relatório não considera transações já enviadas ao agente nem transações já coletadas pelo Google Analytics.
O exemplo de código a seguir pode ajudar você a começar.
/** * The purchase was processed. We will track the transaction and its associated line items * now, but only if the purchase has been confirmed. */ - (void) processPurchase:Purchase purchase { [[GANTracker sharedTracker] addTransaction:[purchase transactionId] totalPrice:[purchase totalPrice] storeName:[purchase store] totalTax:[purchase tax] shippingCost:[purchase shipping] withError:&error]; if (error) { // Handle error } for (PurchaseItem item in [purchase items]) { [[GANTracker sharedTracker] addItem:[purchase transactionId] itemSKU:[item itemSKU] itemPrice:[item price] itemCount:[item count] itemCategory:[item category] withError:&error]; if (error) { // Handle error } } if ([purchase isConfirmed]) { [[GANTracker sharedTracker] trackTransactions:&error]; } else { // The purchase was denied or failed in some way. We need to clear out // any data we've already put in the Ecommerce buffer. [[GANTracker sharedTracker] clearTransactions:&error]; } }
Para mais informações sobre comércio eletrônico, consulte o Guia de acompanhamento de comércio eletrônico.
Anonimizar IP
Para anonimizar as informações de IP do usuário, defina a propriedade anonymizeIp
como YES.
Isso instrui o Google Analytics a anonimizar as informações enviadas pelo SDK removendo o último octeto do endereço IP antes que ele seja armazenado.
Confira um exemplo de como fazer isso:
[[GANTracker sharedTracker] setAnonymizeIp:YES];
Você pode definir anonymizeIp
a qualquer momento.
Como definir a taxa de amostragem
É possível definir a taxa de amostragem usando a propriedade sampleRate
.
Se seu aplicativo gerar muito tráfego do Google Analytics, definir a taxa de amostragem pode impedir que seus relatórios sejam gerados usando dados de amostra. A amostragem ocorre de forma consistente entre usuários únicos, portanto, há integridade na tendência e nos relatórios quando a taxa de amostragem está ativada.
O parâmetro sampleRate
é um NSUInteger e pode ter um valor entre 0 e 100, inclusive. Confira um exemplo que reduz a sampleRate
para 95%:
[[GANTracker sharedTracker] setSampleRate:95];
Uma taxa de 0 desativa a geração de hits, enquanto uma taxa de 100 envia todos os dados para o Google Analytics.
É melhor definir sampleRate
antes de chamar qualquer método de acompanhamento.
Saiba mais sobre amostragem no Guia de conceitos da amostragem.
Agrupar hits
Para reduzir a sobrecarga de conexão e bateria, recomendamos enviar suas solicitações de rastreamento em lotes. Você pode chamar dispatch
no objeto de acompanhamento sempre que quiser fazer uma solicitação em lote, manualmente ou em intervalos de tempo específicos.
Problemas conhecidos
dispatch
nas seguintes situações:
-
No método
applicationWillTerminate
-
No
applicationDidEnterBackground
-
Antes de ligar para
stopTracker
dispatchSynchronous:
.
Acompanhamento de campanhas
Acompanhamento geral de campanhas
Com a versão 1.3 do SDK do Google Analytics para iOS, agora você pode acompanhar referências de campanha. Por exemplo, se seu aplicativo implementar um esquema de URL personalizado, você poderá criar um URL que contenha parâmetros de consulta da campanha. Quando seu aplicativo é iniciado em resposta a esse URL, você pode recuperar os parâmetros de consulta e transmiti-los para setReferrer. Assim, as informações são armazenadas no Google Analytics.
Para definir as informações de referência da campanha, use o método setReferrer
da seguinte maneira:
[[GANTracker sharedTracker] setReferrer:referrer withError:&error];
Há duas restrições ao uso desse recurso. Primeiro, chame startTrackerWithAccountID
antes de
setReferrer
. Você precisa fazer isso porque o banco de dados SQLite usado pelo Google Analytics não está configurado antes de
chamar startTrackerWithAccountID
e setReferrer
precisa desse banco de dados. Se você não chamou
startTrackerWithAccountID
, um erro será retornado.
A segunda restrição é que a string de referência transmitida para setReferrer
precisa seguir um formato específico.
Ele precisa assumir a forma de um conjunto de parâmetros de URL e incluir pelo menos um parâmetro gclid ou utm_campaign, utm_medium e utm_source. No último caso, ela também pode ter os parâmetros utm_term e utm_content.
O parâmetro gclid faz parte do recurso de codificação automática que vincula automaticamente o Google Analytics ao Google Ads. Este é um exemplo de referência de campanha que usa a codificação automática:
referrer = @“gclid=gclidValue”;
A string de referência de campanha manual pode ter esta aparência:
referrer = @“utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;
Se você transmitir uma string de referenciador mal formada para setReferrer
, as informações do referenciador não serão alteradas e você receberá um valor de retorno "false". Um valor de retorno "true" indica que o referenciador foi atualizado e será adicionado a cada hit daqui para frente.
Você também vai receber um erro que pode ser inspecionado para conseguir detalhes sobre o que deu errado caso a chamada falhe.
Uma nova sessão será iniciada quando você chamar setReferrer e ele retornar "true".
Parâmetros do link de referência
Parâmetro | Obrigatório | Descrição | Exemplos |
---|---|---|---|
utm_campaign |
Sim | Nome da campanha. Usado para a análise de palavras-chave a fim de identificar especificamente a promoção de um produto ou uma campanha estratégica | utm_campaign=spring_sale |
utm_source |
Sim | Origem da campanha. Usado para identificar um mecanismo de pesquisa, boletim informativo ou outra origem | utm_source=google |
utm_medium |
Sim | Mídia da campanha. Usado para identificar uma mídia, como e-mail ou custo por clique (CPC, na sigla em inglês) | utm_medium=cpc |
utm_term |
Não | Termo da campanha: usado com a pesquisa paga para fornecer as palavras-chave para os anúncios. | utm_term=running+shoes |
utm_content |
Não | Conteúdo da campanha. Usado para testes A/B e anúncios com segmentação por conteúdo para diferenciar anúncios ou links que direcionam ao mesmo URL |
utm_content=logolink
utm_content=textlink
|