SDK do Google Analytics para iOS v1 (legado)

O SDK do Google Analytics para apps para dispositivos móveis iOS facilita a implementação do Google Analytics em apps baseados 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 usuários em sites tradicionais e interagir com widgets em páginas da Web tradicionais. Por esse motivo, os termos usados abaixo refletem o modelo convencional de acompanhamento de site e estão sendo mapeados para o acompanhamento de aplicativos para dispositivos móveis. Você precisa conhecer o acompanhamento do Analytics para entender como esse SDK funciona.

Use o SDK de acompanhamento de dispositivos móveis para acompanhar seus aplicativos para smartphones 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 de medir o volume de tráfego de um site tradicional. Como os apps para dispositivos móveis não contêm páginas HTML, é necessário decidir quando e com que frequência uma solicitação de visualização de página será acionada. Além disso, como as solicitações de visualização de página são criadas para gerar relatórios sobre as estruturas de diretórios, é necessário fornecer nomes descritivos para que as solicitações aproveitem a nomeação do caminho da página nos relatórios de conteúdo do Google Analytics. Os nomes escolhidos serão preenchidos nos seus relatórios do Google Analytics como caminhos de página, mesmo que não sejam páginas HTML, mas você pode usá-los a seu favor estruturando caminhos para oferecer outros agrupamentos às chamadas.
Acompanhamento de eventos
No Analytics, os eventos são projetados para rastrear a interação do usuário com elementos de páginas da Web de maneira diferente das solicitações de visualização de página. Você pode usar o recurso de acompanhamento de eventos do Google Analytics para fazer outras chamadas que serão informadas na seção "Acompanhamento de eventos" da interface de relatórios do Google Analytics. Os eventos são agrupados usando categorias e também podem usar rótulos por evento, o que oferece flexibilidade nos relatórios. Por exemplo, um app multimídia pode ter ações de reproduzir/parar/pausar para a categoria de vídeo e atribuir um rótulo para cada nome de vídeo. Os relatórios do Google Analytics agregariam eventos para todos os eventos marcados com a categoria video. Para mais informações sobre o acompanhamento de eventos, consulte o Guia de acompanhamento de eventos
Acompanhamento de e-commerce
Use o recurso de acompanhamento de e-commerce para rastrear transações do carrinho de compras e compras no app. 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 comércio eletrônico" da interface do Google Analytics. Para mais informações sobre o acompanhamento de e-commerce, consulte o guia de acompanhamento de e-commerce.
Variáveis personalizadas
As variáveis personalizadas são tags de par com valor e nome que você pode inserir no código de acompanhamento para refinar o acompanhamento do Google Analytics. Para mais informações sobre como você pode 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, bem como a versão Thumb padrão. Para usar a versão NoThumb da biblioteca, use o arquivo libGoogleAnalytics_NoThumb.a em vez do libGoogleAnalytics.a.

Como começar

Requisitos

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

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 seu novo projeto.
  • Inclua o framework CFNetwork no seu projeto e vincule ao libsqlite3.0.dylib.

O SDK do Google Analytics para apps para dispositivos móveis deve funcionar com qualquer iPhone ou iPod Touch com iOS 2.0 ou superior. A biblioteca é compatível com todas as versões do iOS compatíveis com aplicativos nativos.

Um SDK de exemplo está incluído no SDK e demonstra como o projeto deve ser se a configuração for bem-sucedida. Fique à vontade para usá-lo como modelo para seus próprios aplicativos integrados ao Analytics.

Como usar o SDK

Antes de começar a usar o SDK, você precisa criar uma conta sem custo financeiro em www.google.com/analytics e criar uma nova propriedade da Web nessa conta usando um URL de site falso, mas descritivo, (por exemplo, http://mymobileapp.mywebsite.com). Depois de criar a propriedade, anote ou mantenha uma cópia do ID de 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 se reserva o direito de acompanhar e informar anonimamente a atividade de um usuário no seu 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 se inscrever em uma conta.

Exemplos e práticas recomendadas

Veja o exemplo de código e as práticas recomendadas em code.google.com no projeto analytics-api-samples.

Biblioteca EasyTracker

Uma biblioteca do EasyTracker está disponível. Ele oferece rastreamento em nível de aplicativo e UIViewController quase nenhum esforço de desenvolvimento. Ele pode ser encontrado na seção Downloads do projeto analytics-api-samples.

Como iniciar o tracker

Inicie o tracker chamando o método startTrackerWithAccountID no Singleton do tracker obtido via [GANTracker sharedTracker]. Muitas vezes, é conveniente chamar esse método diretamente no método applicationDidFinishLaunching do delegado do seu app. Transmita o ID da propriedade da Web, o período de envio necessá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 visualizaçõ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 Visão geral do SDK acima.

Como usar variáveis personalizadas

Adicionar uma variável personalizada também é simples: basta usar o método setCustomVariableAtIndex fornecido pelo SDK para dispositivos móveis. Planeje com antecedência para que cada índice personalizado será mapeado, de modo que você não substitua nenhuma variável existente anteriormente. Para mais informações sobre variáveis personalizadas, consulte o Guia de variáveis personalizadas. O método setCustomVariableAtIndex não envia dados diretamente. Em vez disso, os dados são enviados com a próxima visualização de página ou evento rastreado. É necessário chamar setCustomVariableAtIndex antes de acompanhar uma visualização de página ou um evento. O escopo padrão das variáveis personalizadas está no escopo da página.

Como usar o acompanhamento de e-commerce

Você pode usar quatro métodos para ativar o acompanhamento de e-commerce em 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. Apenas ao chamar trackTransactions, as transações e os itens serã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: ele não se lembra de nenhuma transação enviada anteriormente ao agente nem de transações já coletadas pelo Google Analytics.

A amostra 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 informa ao Google Analytics para anonimizar as informações enviadas pelo SDK removendo o último octeto do endereço IP antes que ele seja armazenado.

Veja um exemplo de como configurá-la:

 [[GANTracker sharedTracker] setAnonymizeIp:YES];

É possível definir o anonymizeIp a qualquer momento.

Como definir a taxa de amostragem

É possível definir a taxa de amostragem usando a propriedade sampleRate. Se o seu aplicativo gerar muito tráfego do Analytics, a definição da taxa de amostragem poderá impedir que seus relatórios sejam gerados com dados de amostra. A amostragem ocorre de forma consistente em usuários únicos. Sendo assim, há integridade na tendência e na geração de relatórios quando a taxa de amostragem está ativada. O parâmetro sampleRate é um NSUInteger e pode ter valor entre 0 e 100, inclusive. Veja um exemplo que reduz o sampleRate para 95%:

 [[GANTracker sharedTracker] setSampleRate:95];

Uma taxa 0 desativa a geração de hits, enquanto uma taxa 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.

Hits em lote

Para economizar energia e sobrecarga da conexão, recomendamos agrupar as solicitações de acompanhamento em lotes. Você pode chamar dispatch no objeto de acompanhamento sempre que quiser fazer uma solicitação em lote e fazer isso manualmente ou em intervalos de tempo específicos.

Problemas conhecidos

  • Referências/origens de tráfego: no momento, não é possível rastrear a origem da campanha/referência de um download de app no dispositivo iOS.
  • Não recomendamos chamar dispatch nas seguintes situações:
    • No método applicationWillTerminate
    • No applicationDidEnterBackground
    • Antes de ligar para stopTracker
    Isso pode fazer com que os hits sejam enviados duas vezes. Em vez disso, use o método dispatchSynchronous:.
  • Chamar métodos GANTracker em linhas de execução diferentes pode resultar em erros de SQLite ocultos. Faça todas as chamadas na mesma conversa.
  • Acompanhamento de campanhas

    Acompanhamento geral da campanha

    Com a versão 1.3 do SDK do Google Analytics para iOS, você pode acompanhar as referências da campanha. Por exemplo, se o aplicativo implementar um esquema de URL personalizado, você poderá criar um URL que contenha parâmetros de consulta de campanha. Quando seu aplicativo é iniciado em resposta a esse URL, você pode recuperar os parâmetros de consulta e transmiti-los para setreferrer para que as informações sejam 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 para o uso desse recurso. Primeiro, chame startTrackerWithAccountID antes de chamar 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 tiver chamado 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 um de cada, 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. Um exemplo de referência de campanha usando a codificação automática pode ter a seguinte aparência:

    referrer = @“gclid=gclidValue”;
    

    A string de referência da campanha manual pode ser semelhante a esta:

    referrer = @“utm_campaign=campaign&utm_source=source&utm_medium=medium&utm_term=term&utm_content=content”;
    

    Se você passar 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 falso. Um valor de retorno "true" indica que o referenciador foi atualizado e será adicionado a cada hit no futuro. Você também receberá um erro retornado, que pode ser inspecionado para obter detalhes do que deu errado em caso de falha na chamada.

    Além disso, uma nova sessão será iniciada quando você chamar setReferrer e ela 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