Configuração para licenciamento

Antes de começar a adicionar a verificação de licença ao app, você precisa configurar sua conta de publicação do Google Play, seu ambiente de desenvolvimento e todas as contas de teste necessárias para verificar a implementação.

Como configurar uma conta de editor

Caso você ainda não tenha uma conta de editor do Google Play, será preciso fazer o registro usando sua Conta do Google e concordar com os Termos de Serviço do Google Play.

Para saber mais, consulte a seção Primeiros passos com publicações.

Se você já tem uma conta de editor no Google Play, use o Play Console para configurar o licenciamento.

Usando o Google Play Console, você pode:

• conseguir uma chave pública específica do app para fazer o licenciamento;
• depurar e testar a implementação de licenciamento de um app antes de publicá-lo;
• publicar os apps a que você adicionou compatibilidade com o licenciamento.

Configurações administrativas para o licenciamento

É possível gerenciar vários controles administrativos para o licenciamento do Google Play no Play Console. Os controles permitem que você:

• configure várias "contas de teste", que são identificadas pelo endereço de e-mail. O servidor de licenciamento permite que os usuários conectados a contas de teste em um dispositivo ou emulador enviem verificações de licença e recebam respostas estáticas de teste. Você pode configurar contas na página de detalhes da conta do Play Console;
• configure as respostas estáticas de teste que o servidor envia quando recebe uma verificação de licença de um app enviado para a conta do editor de um usuário conectado a ela ou a uma conta de teste. Você pode definir respostas de teste na página de detalhes da conta do Play Console;
• receba a chave pública do app para o licenciamento. Ao implementar o licenciamento em um app, você precisa copiar a string da chave pública no app. Você pode conseguir a chave pública do app para o licenciamento na página "Serviços e APIs" (em "Todos os aplicativos").

Figura 1. A chave de licença de um app está disponível na página "Serviços e APIs" no Play Console.

Para saber mais sobre como trabalhar com contas de teste e respostas estáticas de testes, consulte abaixo Como configurar o ambiente de teste.

Como configurar o ambiente de desenvolvimento

A configuração do ambiente para licenciamento envolve as seguintes tarefas:

1. Configurar o ambiente de execução para desenvolvimento
2. Fazer o download da LVL para o SDK
3. Configurar a Biblioteca Licensing Verification
4. Incluir o projeto da Biblioteca LVL no aplicativo

As seções abaixo descrevem essas tarefas. Quando terminar a configuração, você poderá começar a Adicionar o licenciamento ao app.

Antes de tudo, você precisa configurar um ambiente de execução adequado em que possa executar, depurar e testar a implementação da verificação e da aplicação de licenças no app.

Como configurar o ambiente de execução

Conforme descrito anteriormente, os apps verificam o status de licenciamento sem entrar em contato direto com o servidor. Eles se conectam a um serviço fornecido pelo app Google Play e enviam uma solicitação de verificação de licença. Em seguida, o serviço do Google Play processa a comunicação direta com o servidor de licenciamento e roteia a resposta de volta para o app. Para depurar e testar o licenciamento no seu app, configure um ambiente de execução que inclua o serviço do Google Play necessário para que o app possa enviar solicitações de verificação de licença ao servidor de licenciamento.

Você pode usar dois tipos de ambiente de execução:

• Um dispositivo com tecnologia Android que inclua o app Google Play.
• Um Android Emulator com o complemento de APIs do Google, API de nível 8 (versão 2) ou versão mais recente.

Como executar em um dispositivo

Para usar um dispositivo com tecnologia Android para depurar e testar o licenciamento, ele precisa:

• executar uma versão compatível da plataforma Android 1.5 ou mais recente (API de nível 3 ou mais recente);
• executar uma imagem do sistema em que o app cliente do Google Play esteja pré-instalado.

Se o Google Play não estiver pré-instalado na imagem do sistema, seu app não poderá se comunicar com o servidor de licenciamento dele.

Para ter informações gerais sobre como configurar um dispositivo para usar no desenvolvimento de apps para Android, consulte Como usar dispositivos de hardware.

Como executar em um Android Emulator

Se você não tiver um dispositivo disponível, use um Android Emulator para depurar e testar o licenciamento.

Como as plataformas Android fornecidas no SDK do Android não incluem o Google Play, é necessário fazer o download da plataforma do complemento de APIs do Google, API de nível 8 (ou mais recente), do repositório do SDK. Depois de fazer o download do complemento, você precisará criar uma configuração de AVD que use essa imagem do sistema.

O complemento de APIs do Google não inclui o cliente completo do Google Play. No entanto, ele fornece:

• um serviço em segundo plano do Google Play que implementa a interface remota ILicensingService para que o app possa enviar verificações de licença para o servidor de licenciamento pela rede;
• um conjunto de serviços de conta subjacentes que permitem adicionar uma Conta do Google ao AVD e fazer login usando as credenciais da conta de editor ou de teste.

  Fazer login com a conta de editor ou de teste permite que você depure e teste o app sem ter que publicá-lo. Para saber mais, consulte Como fazer login em uma conta autorizada abaixo.

Várias versões do complemento de APIs do Google estão disponíveis pelo SDK Manager, mas apenas a versão para o Android 2.2 e mais recente inclui os serviços necessários do Google Play.

Para configurar um emulador para adicionar o licenciamento a um app, siga estas etapas:

1. Abra o Android SDK Manager, disponível no menu "Tools" do Android Studio (Tools > Android > SDK Manager) ou execute <sdk>/tools/android sdk.
2. Selecione Google APIs e faça o download para a versão do Android desejada (precisa ser Android 2.2 ou mais recente).
3. Quando o download estiver concluído, abra o AVD Manager, disponível no menu "Tools" do Android Studio (Tools > Android > AVD Manager) ou execute <sdk>/tools/android avd.
4. Na janela Android Virtual Device Manager, selecione + Create Virtual Device para definir os detalhes de configuração do novo AVD.
5. Na janela Virtual Device Configuration, selecione o hardware do dispositivo e selecione Next.
6. Selecione uma API do Google como a imagem do sistema que será executada no novo AVD e selecione Next.
7. Atribua um nome descritivo ao AVD e defina os outros detalhes de configuração conforme necessário.
8. Selecione Finish para criar a nova configuração do AVD, que será exibida na lista de dispositivos virtuais Android disponíveis.

Se você não estiver familiarizado com AVDs ou como usá-los, consulte Gerenciar dispositivos virtuais.

Como atualizar a configuração do seu projeto

Depois de configurar um ambiente de execução que atenda aos requisitos descritos acima, seja em um dispositivo real ou emulador, atualize o projeto do app ou os scripts de compilação do app conforme necessário. Assim, os arquivos .apk compilados que usam o licenciamento serão implantados nesse ambiente. Se você estiver desenvolvendo no Android Studio, não se esqueça de definir uma configuração de execução/depuração para o dispositivo ou AVD apropriado.

Não será necessário fazer alterações na configuração do build do app quando o projeto já estiver configurado para compilar em uma biblioteca padrão do Android 1.5 (API de nível 3) ou versões mais recentes. Adicionar o licenciamento a um app não tem impacto na configuração do build.

Como fazer o download da LVL

A biblioteca License Verification (LVL, na sigla em inglês) é uma coleção de classes auxiliares que simplificam muito o trabalho necessário para adicionar o licenciamento ao app. Em todos os casos, recomendamos que você faça o download da LVL e a use como base para a implementação do licenciamento.

A Biblioteca License Verification (LVL) é desenvolvida no GitHub. Você pode clonar o repositório da LVL (link em inglês) e defini-lo como um projeto de biblioteca. Para clonar o repositório, digite o seguinte na linha de comando:

git clone https://github.com/google/play-licensing

O repositório inclui:

• A fontes da LVL, armazenadas em um projeto de biblioteca do Android.
• Um app de exemplo chamado "sample" que depende do projeto da LVL. Veremos a seguir como um app usa as classes auxiliares da biblioteca para verificar e aplicar o licenciamento.

Como configurar a biblioteca License Verification

Depois de fazer o download da LVL no computador, é necessário configurá-la no ambiente de desenvolvimento, seja como um projeto de biblioteca do Android ou copiando (ou importando) as fontes da biblioteca diretamente para o pacote de apps já existente. Em geral, é recomendável usar a LVL como um projeto de biblioteca porque ela permite que você reutilize o código de licenciamento em vários apps e o mantenha mais facilmente ao longo do tempo. Observe que a LVL não foi desenvolvida para ser compilada separadamente e adicionada a um app como um arquivo .jar estático.

É recomendado usar a LVL como um novo projeto de biblioteca do Android. Um projeto de biblioteca é um tipo de projeto de desenvolvimento que contém códigos-fonte e recursos compartilhados do Android. Outros projetos de apps para Android podem referenciar o projeto de biblioteca e, na hora da compilação, incluir as fontes compiladas nos arquivos .apk. No contexto do licenciamento, isso significa que você pode fazer a maior parte do desenvolvimento do licenciamento de uma só vez em um projeto de biblioteca e incluir as fontes em vários projetos de apps. Dessa forma, você pode manter, de maneira fácil e central, uma implementação uniforme do licenciamento para todos os seus projetos. Se você não estiver familiarizado com os projetos de biblioteca ou como usá-los, consulte Como gerenciar projetos.

A LVL é fornecida como um projeto de biblioteca configurada. Depois de fazer o download, você pode começar a usá-la imediatamente.

Se você estiver trabalhando no Android Studio, precisará adicionar a LVL ao projeto como um novo módulo.

1. Use a janela "Import Module from Source" para importar um módulo da biblioteca selecionando File > New > Import Module.
2. Em Source directory, na janela Import Module from Source, digite o diretório library principal da LVL (ou seja, o diretório que contém o arquivo AndroidManifest.xml da biblioteca) como raiz do projeto (<sdk>/extras/google/play_licensing/library/AndroidManifest.xml) e selecione Next.
3. Selecione Finish para importar o módulo.

Para saber mais sobre como trabalhar com módulos de biblioteca no Android Studio, consulte Criar uma biblioteca Android.

Como incluir as fontes do projeto da LVL no aplicativo

Se você quiser usar as fontes da LVL como um projeto de biblioteca, você precisará adicionar uma referência ao projeto da LVL às propriedades do projeto do app. Isso dirá às ferramentas de build para incluir as origens de projeto da LVL no aplicativo no momento da compilação. O processo para adicionar uma referência a um projeto de biblioteca depende do seu ambiente de desenvolvimento, conforme descrito abaixo.

Se estiver desenvolvendo no Android Studio, você provavelmente já terá adicionado o módulo da biblioteca ao projeto, conforme descrito na seção anterior. Se ainda não tiver feito isso, faça antes de continuar.

Se você estiver desenvolvendo com as ferramentas de linha de comando do SDK, navegue até o diretório que contém o projeto do seu app e abra o arquivo project.properties. Adicione uma linha ao arquivo, especificando a chave android.library.reference.<n> e o caminho para a biblioteca. Exemplo:

android.library.reference.1=path/to/library_project

Como alternativa, você pode usar esse comando para atualizar as propriedades do projeto, incluindo a referência ao projeto de biblioteca:

android update lib-project
--target <target_ID> \
--path path/to/my/app_project \
--library path/to/my/library_project

Para saber mais sobre como trabalhar com projetos de biblioteca, consulte Como configurar um projeto de biblioteca.

Como configurar o ambiente de testes

O Google Play Console fornece ferramentas de configuração que permitem que você e outras pessoas testem o licenciamento no app antes de publicá-lo. Ao implementar o licenciamento, você pode usar as ferramentas do Play Console para testar a interface Policy do seu app e processar as diferentes respostas de licenciamento e condições de erro.

Os principais componentes do ambiente de testes para licenciamento são estes:

• Uma configuração de "Resposta de teste" na conta de editor que permite definir a resposta estática de licenciamento retornada quando o servidor processa uma verificação de licença de um app enviado para aquela conta de um usuário conectado a ela ou a uma conta de teste.
• Um conjunto opcional de contas de teste que receberá a resposta de teste estática quando verificarem a licença de um app que você enviou (não faz diferença se o app está publicado ou não).
• Um ambiente de execução para o app que inclui o app Google Play ou o Complemento de APIs do Google, em que o usuário está conectado à conta de editor ou a uma das contas de teste.

A configuração correta do ambiente de teste envolve:

1. definir respostas estáticas de teste retornadas pelo servidor de licenciamento;
2. definir contas de teste conforme o necessário;
3. fazer login corretamente em um emulador ou dispositivo antes de iniciar um teste de verificação de licença.

As seções a seguir oferecem mais informações.

Como definir respostas de teste para verificações de licença

No Google Play, há uma configuração na sua conta de editor que permite modificar o processamento normal de uma verificação de licença e retornar um código de resposta estática especificado. A configuração é válida apenas para testes e se aplica apenas a verificações de licença de apps enviadas por você e feitas por qualquer usuário conectado a um emulador ou dispositivo usando as credenciais da conta de editor ou de uma conta de teste registrada. Para outros usuários, o servidor sempre processa verificações de licença de acordo com as regras normais.

Para definir uma resposta de teste para sua conta, faça login em sua conta de editor e clique em "Editar perfil". Na página "Editar perfil", localize o menu "Resposta de teste" no painel "Licenciamento", mostrado abaixo. Você pode selecionar opções no conjunto completo de códigos de respostas válidas do servidor para controlar a resposta ou a condição que quer testar no app.

No geral, você precisa testar a implementação de licenciamento do seu app com cada código de resposta disponível no menu "Resposta de teste". Para ver uma descrição dos códigos, consulte Códigos de resposta do servidor na Referência de licenciamento.

Figura 2. O painel "Teste de licença" da página de detalhes da conta permite configurar contas e gerenciar respostas de teste.

A resposta de teste que você configurar será aplicada a todas as contas, ou seja, não a um único app, mas a todos os apps associados à conta de editor. Se você estiver testando vários apps ao mesmo tempo, mudar a resposta de teste afetará todos eles na próxima verificação de licença (se o usuário tiver feito login no emulador ou dispositivo usando a conta de editor ou de teste).

Antes de receber uma resposta de teste para uma verificação de licença, faça login no dispositivo ou emulador em que o app está instalado e de onde ele está consultando o servidor. Especificamente, é necessário assiná-lo usando sua conta de editor ou uma das contas de teste que você configurou. Para saber mais sobre contas de teste, consulte a próxima seção.

Consulte Códigos de resposta do servidor para ver uma lista de respostas de teste disponíveis e os significados de cada uma delas.

Como configurar contas de teste

Em alguns casos, convém permitir que várias equipes de desenvolvedores testem o licenciamento em apps que serão publicados pela sua conta de editor, mas sem conceder acesso às credenciais de login da sua conta. Para isso, o Google Play Console permite que você configure uma ou mais contas de teste opcionais. Elas estão autorizadas a consultar o servidor de licenciamento e receber respostas estáticas de teste na sua conta de editor.

As contas de teste são Contas do Google padrão registradas na sua conta de editor para receber resposta de teste dos apps de que você fez o upload. Os desenvolvedores podem fazer login nos dispositivos ou emuladores com as credenciais da conta de teste e iniciar verificações de licença nos apps instalados. Quando o servidor de licenciamento recebe uma verificação de licença de um usuário de uma conta de teste, ele retorna a resposta estática de teste configurada para a conta do editor.

Há limitações no acesso e nas permissões concedidas aos usuários conectados em contas de teste, incluindo:

• Os usuários da conta de teste podem consultar o servidor de licenciamento somente para apps cujo upload na conta de editor já tenha sido concluído.
• Os usuários da conta de teste não têm permissão para fazer upload de apps na conta de editor.
• Os usuários da conta de teste não têm permissão para definir a resposta estática de teste da conta de editor.

A tabela abaixo resume as diferenças de recursos entre a conta do editor, uma conta de teste e qualquer outra conta.

Tabela 1. Diferenças nos tipos de conta para testes de licenciamento.

Como registrar contas de teste na conta de editor

Para começar, você precisa registrar cada conta de teste na conta de editor. Conforme mostrado na Figura 2, você registra as contas de teste no painel "Licenciamento" da página "Editar perfil" da conta de editor. Basta inserir as contas como uma lista delimitada por vírgulas e clicar em Salvar para salvar as alterações do perfil.

É possível usar qualquer Conta do Google como uma conta de teste. Se quiser ter mais controle sobre as contas de teste, crie-as e distribua as credenciais para os desenvolvedores ou testadores.

Como processar o upload e a distribuição de apps para usuários de contas de teste

Como mencionado acima, os usuários de contas de teste podem receber respostas estáticas de teste apenas para apps já enviados para a conta de editor. Como esses usuários não têm permissão para fazer o upload de apps, você precisará trabalhar com eles para coletar apps para upload e distribuir os apps enviados para teste. Você pode processar a coleta e a distribuição como preferir.

Depois que um app é enviado e se torna conhecido pelo servidor de licenciamento, os desenvolvedores e testadores podem continuar a modificá-lo no ambiente de desenvolvimento local, sem precisar fazer o upload de novas versões. Você só precisará fazer o upload de uma nova versão se o app local incrementar o atributo versionCode no arquivo de manifesto.

Como distribuir a chave pública a usuários da conta de teste

O servidor de licenciamento gerencia as respostas estáticas de teste normalmente, o que inclui assinar os dados de resposta da licença, adicionar parâmetros extras etc. Para oferecer compatibilidade a desenvolvedores que estão implementando o licenciamento com contas de teste em vez de editor, você precisará distribuir a chave pública do app. Os desenvolvedores que não têm acesso ao Play Console também não têm acesso à chave pública do app e, sem ela, não podem verificar as respostas de licença.

Se, por algum motivo, você decidir gerar um novo par de chaves de licenciamento para o app, será necessário notificar todos os usuários das contas de teste. Para os testadores, você pode incorporar a nova chave no pacote do app e distribuir aos usuários. Para os desenvolvedores, você precisa distribuir a nova chave diretamente.

Como fazer login em uma conta autorizada no ambiente de execução

O serviço de licenciamento foi desenvolvido para determinar se um usuário está licenciado para usar um determinado app. Durante uma verificação de licença, o app Google Play coleta o ID do usuário da conta principal no sistema e envia ao servidor junto com o nome do pacote do app e outras informações. No entanto, se não houver informações de usuário disponíveis, a verificação de licença não poderá ser concluída. O app Google Play encerrará a solicitação e retornará um erro ao app.

Durante o teste, para garantir que seu app possa consultar o servidor de licenciamento, verifique se fez login em uma conta no dispositivo ou emulador usando:

• as credenciais de uma conta de editor;
• as credenciais de uma conta de teste registrada em uma conta de editor.

Fazer login com uma conta de editor tem a vantagem de permitir que seus apps recebam respostas estáticas de teste antes mesmo de serem enviados para o Play Console.

Se você faz parte de uma organização maior ou está trabalhando com grupos externos em apps que serão publicados no seu site, convém distribuir contas de teste e usá-las para fazer login durante os testes.

Para fazer login em um dispositivo ou emulador, siga as etapas abaixo. A abordagem preferencial é fazer login como conta principal. No entanto, se houver outras contas em uso no dispositivo ou emulador, você poderá criar outra conta e fazer login usando as credenciais da conta de editor ou de teste.

1. Abra "Configurações > Contas e sincronização".
2. Selecione Adicionar conta e escolha adicionar uma Conta do Google.
3. Selecione Próxima e Fazer login.
4. Insira o nome de usuário e a senha da conta de editor ou de uma conta de teste registrada na conta de editor.
5. Selecione Fazer login. O sistema fará login na nova conta.

Depois de fazer login, você poderá começar a testar o licenciamento no app se tiver concluído as etapas de integração da LVL acima. Quando o app iniciar uma verificação de licença, ele receberá um retorno com a resposta estática de teste configurada na conta de editor.

Se você estiver usando um emulador, será necessário fazer login na conta de editor ou de teste sempre que apagar os dados ao reiniciar o emulador.

Depois de concluir os procedimentos de configuração, continue em Adicionar licenciamento ao app.