SDK do Google Analytics para iOS v1 (legado)

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étodo addItem 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 arquivo libGoogleAnalytics.a.

Como começar

Requisitos

Para integrar os recursos de acompanhamento do Google Analytics ao seu app iOS, você precisará de:

Configuração

  • Abra o Xcode e crie um novo projeto do sistema operacional do iPhone.
  • Arraste GANTracker.h e libGoogleAnalytics.a do diretório da Biblioteca do SDK para o novo projeto.
  • Inclua o framework CFNetwork no seu projeto e vincule a libsqlite3.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

  • Referências/origens de tráfego: no momento, não é possível acompanhar a origem da campanha/referência de um download de aplicativo no dispositivo iOS.
  • Não é recomendável chamar dispatch nas seguintes situações:
    • No método applicationWillTerminate
    • No applicationDidEnterBackground
    • Antes de ligar para stopTracker
    Isso pode resultar no envio de hits duas vezes. Em vez disso, use o método dispatchSynchronous:.
  • Chamar métodos GANTracker em linhas de execução diferentes pode resultar em erros obscuros do SQLite. Faça todas as chamadas na mesma linha de execução.

    • 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â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