ÍNDICE. I Livraria npay para Android Resumo Pré-requisitos. 4 3 Requisitos mínimos 4

Transcrição

1

2 ÍNDICE I Livraria npay para Android Resumo Pré-requisitos. 4 3 Requisitos mínimos 4 4 Apoio Projeto Demo 4 5 Modo SandBox. 5 6 Instruções de aplicação da Livraria Importar Archivo Jar ao projeto Android Proporcionar Autorizações Aplicação Básica Funcionalidades e Exemplos Obter Catálogo de Itens Consultar Compras Anteriores Realizar Compras 15 8 Referências Consultar transações via API Definição Códigos de resposta FAQs Glossário... 21

3 Livraria npay para Android npay é uma plataforma de cobro, um sistema processador de pagamentos por operador. Atualmente NARANYA está integrado a 20 Operadores em 7 países diferentes, o objetivo de npay é o de estabelecer uma conexão entre os milhões de Programadores e os principais Operadores Móveis de todo o mundo. npay permitirá a qualquer programador integrar soluções de Cobro por Operador às suas aplicações ou conteúdos, sem importar a plataforma em que esta aplicação seja programada (Multiplataforma). npay se integra constantemente com novos operadores, e se poderão consultar desde a consola do programador para conhecer os operadores disponíveis atualmente. 1. Resumo Para facilitar a integração do sistema de pagamento em aplicações com cobro inapp purchase desenvolvidas em Android, se criou uma Livraria com a qual o programador poderá configurar e executar as seguintes ações: A. Consultar o catálogo de itens previamente configurados pelo programador. B. Verificação de compras anteriores de um consumidor. C. Realizar a ação de uma compra. Adicionalmente, é possível consultar as transações realizadas através da Livraria Android, mediante uma consulta direta à API REST de npay. Isto permite ao programador obter o estado de uma transação mediante comunicação servidor a servidor A identificação do consumidor é da responsabilidade da livraria e se realizará automaticamente em cada transação executada. Na transacção de cobro é possível recuperar um id de consumidor (id_customer) proporcionado por npay.

4 2. Pré-requisitos A. Estar registrado como programador. B. Ter aprovado ao menos uma aplicação com cobros inapp. C. Ter gerado o sdk_key para a aplicação que se deseja aplicar D. Ter configurado ao menos um item de cobro. E. Opcionalmente configurar a aplicação em modo SandBox F. Descarregar o Arquivo JAR da livraria. Pode descarregá-la fazendo clique aqui 3. Requisitos mínimos A. Android 2.2 ou posterior. 4. Apoio Projeto Demo Para exemplificar a aplicação completa das funcionalidades da Livraria, desenvolvemos o projeto Demo NPaySDKDemoApp utilizando a versão SDK de Android (API 21) que se poderá descarregar aqui. Somente se deverá substituir o comentário <!-- Your sdk_key goes here --> na linha 23 do arquivo AndroidManifest.xml com o sdk_key da aplicação que se deseje emular. Para um melhor entendimento da aplicação das funcionalidades da livraria poderás referirte à seção Instruções de Aplicação.

5 5. Modo SandBox É possível realizar provas de aplicação da Livraria em modo SandBox, sem que estas afetem a consumidores e contas reais. Para isso é necessário ativar o modo SandBox na Configuração da Aplicação e estabelecer o resultado esperado das transações de cobro. Quando uma aplicação tem o modo SandBox ativado, a Livraria identificará um consumidor com uma conta móbil fictícia configurada unicamente para o operador Telcel- MX e todas as transações se realizarão com cargo fictícios à dita conta. O resultado da transação executada será configurado no modo SandBox. O modo SandBox usa o Catálogo real da aplicação, pelo que este deve ter pelo menos um item configurado com cobro para Telcel-MX. NOTA: Cada vez que se ative/desative o modo SandBox, se deverão eliminar os dados guardados pela aplicação no dispositivo a utilizar, ou na sua falta, desinstalar a App e voltar a instalar. Isto evitará inconsistências nas provas. 6. Instruções de aplicação da Livraria Para aplicar a Livraria se deverão seguir os seguintes passos: A. Importar o arquivo Jar do projeto Android. B. Proporcionar autorizações. C. Aplicação básica. A. Importar Archivo Jar ao projeto Android Este guia assume que estarás utilizando Eclipse/ADT. 1. Copiar o Arquivo JAR na pasta "libs" do projeto

6 2. Dar clique direito sobre o projeto onde se aplicará a livraria e selecionar Propriedades. 3. Selecionar no menu a opção de Java Build Path e na etiqueta Libraries. 4. Dar clique sobre o botão Add JARs...

7 5. Agregar o arquivo JAR previamente descarregado e colocá-lo na carpeta libs.

8 6. Dar clique em OK B. Proporcionar Autorizações o Dentro do arquivo AndroidManifest.xml de cada aplicação se deverão agregar as seguintes declarações: 1. Permitir aceso a Internet.

9 2. Permitir aceso ao estado de rede. 3. Permitir ler o estado do telefone. 4. Compatibilidade com Tablet. 5. sdk_key da aplicação. O arquivo AndroidManifest.xml resultante será:

10 C. Aplicação Básica Para poder utilizar as funcionalidades proporcionadas pela Livraria, é necessário instanciar um objeto da classe NPay realizando os seguintes passos: o Importar o paquete com a classe NPay da livraria o Inicializar o objeto NPay, passando como parâmetro ao seu construtor o Activity no que se está implementando. o Com o anterior, se podem realizar as chamadas aos métodos contidos na classe. Exemplo: MainActivity.java

11 7. Funcionalidades e Exemplos As funcionalidades disponíveis do Objeto são as seguintes: A. Obter Catálogo de Itens B. Consultar Compras Anteriores C. Realizar Compras Para realizar uma transação de cobro se sugere executar as funcionalidades na ordem descrita anteriormente, porém não á obrigatório e/ou poderão utilizar-se de acordo às necessidades do programador. Para poder executar as funcionalidades se assume que a Aplicação básica da Livraria foi realizada. A. Obter Catálogo de Itens Para obter o catálogo de item se deverá executar o método NPay.getNpayCatalog().getCatalog() Para isso é necessário aplicar os seguintes passos: 1. Importar no código as seguintes livrarias: 2. Depois de instanciar o objeto NPay, declarar e aplicar a interface OnCatalogReceivedListener na que se receberão os itens do catálogo. 3. Aplicar o método OnCatalogReceived dentro da definição anterior de OnCatalogReceivedListener, para processar a informação dos itens

12 Este método recebe como parâmetros dos valores: int responsetype y List&LT; NPayCatalogItem&GT; result I. responsetype Indica a maneira em que se obtiveram os itens; seus valores possíveis são: NPayConstants.CATALOG_ITEMS: Itens recebidos mediante a chamada de obtenção do Catálogo. NPayConstants.PURCHASED_ITEMS: Itens recebidos mediante a chamada de recuperação de compras anteriores Recomenda-se utilizar um condicional switch case para executar as ações desejadas dependendo do tipo de chamada que se executou. Exemplo: II. List&LT;NPayCatalogItem&GT; result Objeto List cujos elementos são instâncias do objeto NPayCatalogItem. Mediante os métodos públicos deste objeto (Veja-se seção Referências) se poderá obter a informação do item. Recomenda-se aplicar um ciclo para recorrer os itens recebidos. Exemplo: III. Estabelecer o objeto definido da interface OnCatalogReceivedListener à instancia de NPay mediante o seguinte método:

13 IV. Executar o método getcatalog() para obter o catálogo de itens previamente configurados. Dever-se-á colocar este método em qualquer ação que o necessite. Exemplo: MainActivity.java B. Consultar Compras Anteriores NOTA: Só se podem obter as compras Anteriores de Itens Não Consumíveis, para fazê-lo o consumidor deve estar registrado em npay, já que é requerido um processo de Login. Para obter as Compras Anteriores de um consumidor, se deverá executar o método NPay.getNpayCatalog().getPurchasedNonConsumableItems() Para isso, é necessário aplicar os seguintes passos: 1. Importar no código as seguintes livrarias: 2. Depois de instanciar o objeto NPay, declarar e aplicar a interface OnCatalogReceivedListener na que se receberão os itens do catálogo.

14 3. Aplicar o método OnCatalogReceived dentro da definição anterior de OnCatalogReceivedListener, para processar a informação dos itens. Este método recebe como parâmetros dos valores: Int responsetype y Lis &LTPayCatalogItem&GT; result I. responsetype Indica a maneira em que se obtiveram os itens; os seus valores possíveis são: NPayConstants.CATALOG_ITEMS: Itens recebidos mediante a chamada de obtenção do Catálogo. NPayConstants.PURCHASED_ITEMS: Itens recebidos mediante a chamada de recuperação de compras anteriores. Recomenda-se utilizar um switch case condicional para executar as ações desejadas dependendo do tipo de chamada que se executou. Exemplo: II. List&LT;NPayCatalogItem&GT; result Objeto List cujos elementos são instâncias do objeto NPayCatalogItem. Mediante os métodos públicos deste objeto (Veja-se seção Referências) se poderá obter a informação do item. Recomenda-se aplicar um ciclo para recorrer os itens recebidos. Exemplo:

15 4. Estabelecer o objetivo definido da interface OnCatalogReceivedListener na instância de NPay mediante o seguinte método: 5. Executar o método getpurchasednonconsumableitems() para obter as compras Anteriores do consumidor. Dever-se-á colocar este método em qualquer ação que o necessite. Exemplo: MainActivity.java C. Realizar Compras Para realizar um pedido de compra, se deverá executar o método NPay.requestPurchase(String sku) Para isso é necessário aplicar os seguintes passos: 1. Importar no código as seguintes livrarias: 2. Depois de instanciar o objeto NPay, declarar e aplicar a interface OnPurchaseDataListener na que se receberá a resposta da transação de cobro.

16 3. Aplicar o método onpurchasedatareceive dentro da definição anterior de OnPurchaseDataListener, para processar a resposta da transação. Este método recebe como parâmetro uma instância do objeto NPayResponseData. Mediante os métodos públicos deste objeto (Véase sección Referencias), se poderá obter a informação da transação. 4. Estabelecer o objetivo definido da interface OnPurchaseDataListener à instancia de NPay mediante o seguinte método: 5. Executar o método requestpurchase(string sku) para realizar um pedido de compra. Este método recebe como parâmetro o sku do item a cobrar. Pode estabelecer-se manualmente no código ou ser obtido de um dos itens recebidos no Catálogo de Itens da aplicação. Se deverá colocar este método em qualquer ação na que se necessite realizar um pedido de cobro Exemplo: MainActivity.java

17 8. Referências Existem dois objetivos com diferentes métodos e cada um deles com um valor específico: A. npaycatalogitem B. npaycatalogitem A. NPayCatalogItem Objetivo que define cada Item do Catálogo da aplicação Métodos Tipo Valor getformattedbaseprice(); String Preço base em USD formatado, por exemplo, 2.00 USD getformattedlocalprice(); String Preço em moeda local formatado, por exemplo, 9.99 MXND getname(); String Nome do item getdescription(); String Descrição do item ispurchased(); Boolean Indicador se o item foi adquirido (true false) isconsumable() Boolean Indicador se o item é consumível (true false) getid_item(); String ID único do item getsku(); String SKU do item geti_type(); int Tipo de item: 0 Consumível, 1 Não consumível tostring(); String Cadeia descritiva do objeto NPayCatalogItem

18 B. NPayResponseData Objeto que define a resposta de uma transação de cobro. Métodos Tipo Valor getid_checkout(); String ID do checkout gerado getid_trx(); String ID da transação gerada getsku(); String SKU do item comprado getid_customer(); String ID do cliente de npay getstatus(); String Estado do checkout: "success" "failed"

19 9. Consultar transações via API A. Definição É possível consultar as transações realizadas através da Livraria Android, mediante uma consulta direta à API REST de npay. Isto permite ao programador obter o estado de uma transação mediante comunicação servidor a servidor. Para realizar um pedido à API, se requere que a App tenha um sdk_key válido e o id_checkout que se deseja consultar, este último obtido na resposta do pedido de compra na Livraria Android. A continuação se descreve a forma como realizar o pedido. Endpoint: Método Argumentos: sdk_keyid_checkout (En la URL de la petición) Exemplo de Resposta: B. Códigos de resposta Código Estado Descrição (Exemplo) 200 OK SUCESSO 400 BAD REQUEST Está faltando um parâmetro obrigatório, erro de digitação de Parâmetro (String em vez deinteger) 401 UNAUTHORIZED O sdk_key não existe, o sdk_key está faltando, O sdk_key expirou, está inválido ou foi revogado 404 NOT FOUND O identificador de recurso é inválido 500 INTERNAL ERROR Comportamento inesperado, arquivos corrompidos, Plataforma congelada 503 SERVICE UNAVAILABLE Manutenção programada em andamento

20 10. FAQs Como obter o SKU? O SKU é um identificador de item e poderá ser definido pelo próprio programador no momento de incluir um item. Como obter o sdk_key? O sdk_key se obtém ao momento de incluir uma aplicação com compras inapp na consola. Como agregar itens? Os itens se agregam desde a consola do programador. Como identificar um consumidor? Os consumidores poderão ser identificados através de um Id de consumidor (id_customer) proporcionado por npay através da livraria nas transações de cobro. Como efetuar um cobro? Para efetuar um cobro se deverá empregar o método: requestpurchase(string sku). Para saber como aplicar o método deverá referir-se à seção Realizar Compra da documentação Como obter compras Anteriores por um consumidor? Para obter as compras Anteriores de um consumidor se deverá empregar o método: getpurchasednonconsumableitems().para saber como aplicar o método deverá referirse à seção Consultar Compras Anteriores da documentação. Como identifico com que operadores telefónicos posso cobrar? Desde o sitio se poderão saber os operadores telefónicos com os que se pode realizar uma transação de cobro. Porque não aparece o diálogo de cobro? Se, ao executar a transação de cobro não se mostram os diálogos correspondentes, se deverá verificar a correta aplicação do método de transação de cobro requestpurchase(srting sku). Para saber como aplicar o método deverá referir-se à seção Realizar Compra da documentação. Porque não se pode obter a lista de itens? Se deverá verificar a correta aplicação do método de obtenção de catálogo getcatalog(). Para saber como aplicar o método deverá referir-se à seção Obter Catálogo de Itens da documentação. Porque não se obteve resposta do cobro? Se deverá validar a correta aplicação do métodorequestpurchase(string sku). Em alguns casos poderia existir saturação por parte do operador telefónico pelo que se recomenda que realize uma vez mais a transação.

21 11. Glossário npay npay é a plataforma de cobro de Naranya. É um sistema processador de pagos que permite a programadores aplicar o cobro via operador telefónico. SDK Key Chave única gerada por aplicação pelo servidor quando a App é criada por um programador. Deve ser incluída no arquivo AndroidManifest.xml da aplicação. Permite à aplicação interatuar de maneira segura com a Livraria e a API de npay. Compra In-App (In-App Purchase) Funcionalidade de uma aplicação que lhe permite oferecer aos consumidores uma variedade de itens adicionais diretamente dentro da aplicação. Item Cada um dos produtos ou serviços que se configuram e oferecem como In-App Purchase. SKU SKU ou Stock-keeping unit, (número de referencia) é um identificador usado no comércio com o objetivo de permitir o seguimento sistemático dos produtos e serviços oferecidos aos clientes. Cada SKU se associa com um objeto, produto, marca, serviço, cargos, etc. Item Consumível (Consumable Item) São itens de um uso ou com um número máximo de usos e que desaparecem ou perdem efeito uma vez que se utilizam o número de vezes que se definiu. Só podem ser utilizados se são adquiridos novamente e podem ser acumuláveis. Por exemplo, vidas em um jogo, poções de recuperação, munições, etc. Item Não Consumível (Non Consumable Item) São itens sem um limite de uso ou de uso permanente. Por exemplo, níveis em um jogo, filtros fotográficos, personagens desbloqueáveis, etc. Catálogo de Itens É o conjunto de Itens configurados na aplicação e que podem ser adquiridos pelo consumidor. API Interface de programação de aplicações (IPA) ou API (do inglês Application Programming Interface) é o conjunto de funções e procedimentos (ou métodos, na programação orientada a objetos) que oferece certa biblioteca para ser utilizado por outro software como uma capa de abstração. REST REST, Representational State Transfer, é um tipo de arquitetura de desenvolvimento web que se apoia totalmente na norma HTTP. REST permite criar serviços e aplicações que podem ser usadas por qualquer dispositivo ou cliente que entenda HTTP, pelo que é mais

22 simples e convencional que outras alternativas que se tenham usado nos últimos anos como SOAP y XML-RPC.