Librería npay para Android

Transcripción

1

2 INDICE I Librería npay para Android. 3 1 Resumen Prerrequisitos. 4 3 Requerimientos mínimos. 4 4 Apoyo Proyecto Demo Modo SandBox 5 6 Instrucciones de implementación de la Librería Importar Archivo Jar al proyecto Android Proporcionar Permisos Implementación Básica 10 7 Funcionalidades y Ejemplos Obtener Catálogo de Items Consultar Compras Previas Realizar Compra Referencias Consultar transacciones vía API Definición Códigos de respuesta FAQs Glosario. 22

3 Librería npay para Android npay es una plataforma de cobro, un sistema procesador de pagos por operador. Actualmente NARANYA está integrado a 20 Operadores en 7 diferentes países, el objetivo de npay es el de establecer una conexión entre los millones de Desarrolladores y los principales Operadores Móviles de todo el mundo. npay le permitirá a cualquier desarrollador, integrar soluciones de Cobro por Operador a sus aplicaciones o contenidos, sin importar la plataforma en la que esta aplicación sea desarrollada (Multiplataforma). npay constantemente se integra con nuevos operadores, para conocer los operadores disponibles actualmente se podrá consultar desde la consola del desarrollador. 1. Resumen Para facilitar la integración del sistema de pago en aplicaciones con cobro inapp purchase desarrolladas en Android, se ha creado unalibrería con la cual el desarrollador podrá configurar y ejecutar las siguientes acciones: A. Consultar el catálogo de ítems previamente configurados por el desarrollador. B. Verificación de compras anteriores de un consumidor. C. Realizar la acción de una compra. Adicionalmente, es posible consultar las transacciones realizadas a través de la Librería Android, mediante una consulta directa a laapi REST de npay. Esto permite al desarrollador obtener el estado de una transacción mediante comunicación server to server La identificación del consumidor es responsabilidad de la librería y se realizará automáticamente en cada transacción ejecutada. En la transacción de cobro es posible recuperar un id de consumidor (id_customer) proporcionado por npay.

4 2. Prerrequisitos A. Estar dado de alta como desarrollador. B. Tener aprobada al menos una aplicación con cobros inapp. C. Haber generado el sdk_key para la aplicación que se desea implementar D. Haber configurado al menos un ítem de cobro. E. Opcionalmente configurar en modo SandBox la aplicación F. Opcionalmente configurar en modo SandBox la aplicación G. Descargar el Archivo JAR de la librería. Puedes descargarla haciendo click aqui 3. Requerimientos mínimos A. Android 2.2 o posterior. 4. Apoyo Proyecto Demo Para ejemplificar la implementación completa de las funcionalidades de la Librería, hemos desarrollado el proyecto DemoNPaySDKDemoApp utilizando la versión SDK de Android (API 21) que se podrá descargar aquí. Solamente se deberá sustituir el comentario <!-- Your sdk_key goes here --> en la línea 23 del archivo AndroidManifest.xml con el sdk_key de la aplicación que se desee emular. Para un mejor entendimiento de la implementación de las funcionalidades de la librería podrás referirte a la sección Instrucciones de Implementación.

5 5. Modo SandBox Es posible realizar pruebas de implementación de la Librería en modo SandBox, sin que éstas afecten a consumidores y cuentas reales. Para ello es necesario activar el modo SandBox en la Configuración de la Aplicación y establecer el resultado esperado de las transacciones de cobro. Cuando una aplicación tiene el modo SandBox activado, la Librería identificará a un consumidor con una cuenta móvil ficticia configurada únicamente para el operador Telcel- MX y todas las transacciones se realizarán con cargo ficticio a dicha cuenta. El resultado de la transacción ejecutada será el configurado en el modo SandBox. El modo SandBox hace uso del Catálogo real de la aplicación, por lo que éste debe tener al menos un item configurado con cobro para Telcel-MX. NOTA: Cada vez que se active/desactive el modo SandBox, se deberán eliminar los datos almacenados por la aplicación en el dispositivo a utilizar, o en su defecto desinstalar la App y volverla a instalar. Esto evitará inconsistencias en las pruebas. 6. Instrucciones de implementación de la Librería Para implementar la Librería se deberán seguir los siguientes pasos: A. Importar el archivo Jar del proyecto Android. B. Proporcionar permisos. C. Implementación básica. A. Importar Archivo Jar al proyecto Android o Esta guía asume que estarás utilizando Eclipse/ADT.

6 1. Copiar el Archivo JAR en la carpeta "libs" del proyecto 2. Dar click derecho sobre el proyecto en donde se implementará la librería y seleccionar Propiedades. 3. Seleccionar el menú la opción de Java Build Path y la pestaña Libraries.

7 4. Dar click sobre el botón Add JARs Agregar el archivo JAR previamente descargado y agregado en la carpeta libs.

8 6. Dar click en OK B. Proporcionar Permisos o Dentro del archivo AndroidManifest.xml de cada aplicación se deberán agregar las siguientes declaraciones: 1. Permitir acceso a Internet.

9 2. Permitir acceso al estado de la red. 3. Permitir leer el estado del teléfono. 4. Compatibilidad con Tablet. 5. sdk_key de la aplicación. El archivo AndroidManifest.xml resultante será:

10 C. Implementación Básica Para poder utilizar las funcionalidades proporcionadas por la Librería, es necesario instanciar un objeto de la clase NPayrealizando los siguientes pasos: 1. Importar el paquete con la clase NPay de la librería 2. Inicializar el objeto NPay, pasando como parámetro a su constructor el Activity en el que se está implementando. 3. Con lo anterior, se pueden realizar las llamadas a los métodos contenidos en la clase. Ejemplo:MainActivity.java

11 7. Funcionalidades y Ejemplos Las funcionalidades disponibles del Objeto son las siguientes: A. Obtener Catálogo de Items B. Consultar Compras Previas C. Realizar Compra Para realizar una transacción de cobro se sugiere ejecutar las funcionalidades en el orden descrito anteriormente, sin embargo no es obligatorio y/o podrán utilizarse de acuerdo a las necesidades del desarrollador. Para poder ejecutar las funcionalidades se asume que la implementación básica de la Librería ha sido realizada. A. Obtener Catálogo de Items Para obtener el catálogo de items se deberá ejecutar el método NPay.getNpayCatalog().getCatalog() Para ello es necesario implementar los siguientes pasos: 1. Importar en el código las siguientes librerías: 2. Después de instanciar el objeto NPay, declarar e implementar la interfaz OnCatalogReceivedListener en la que se recibirán los items del catálogo.

12 3. Implementar el método OnCatalogReceived dentro de la definición anterior de OnCatalogReceivedListener, para procesar la información de los items Este método recibe como parámetros dos valores: int responsetype y List&LT; NPayCatalogItem&GT; result I. responsetype Indica la manera en que se obtuvieron los items; sus valores posibles son: NPayConstants.CATALOG_ITEMS: Items recibidos mediante la llamada de obtención del Catálogo. NPayConstants.PURCHASED_ITEMS: Items recibidos mediante la llamada de recuperación de compras previas Se recomienda utilizar un condicional switch case para ejecutar las acciones deseadas dependiendo del tipo de llamada que se ejecutó. Ejemplo: II. List&LT;NPayCatalogItem&GT; result Objeto List cuyos elementos son instancias del objetonpaycatalogitem. Mediante los métodos públicos de este objeto (Véase sección Referencias) se podrá obtener la información del item. Se recomienda implementar un bucle para recorrer los items recibidos. Ejemplo:

13 III. Establecer el objeto definido de la interfaz OnCatalogReceivedListener a la instancia de NPay mediante el siguiente método: IV. Ejecutar el método getcatalog() para obtener el catálogo de items previamente configurados. Se deberá colocar este método en cualquier acción que lo requiera. Ejemplo: MainActivity.java B. Consultar Compras Previas NOTA: Solamente se pueden obtener las compras previas de Items No Consumibles, para hacerlo el consumidor debe estar registrado en npay, ya que es requerido un proceso de Login. Para obtener las Compras Previas de un consumidor, se deberá ejecutar el métodonpay.getnpaycatalog().getpurchasednonconsumableitems() Para ello, es necesario implementar los siguientes pasos: 1. Importar en el código las siguientes librerías:

14 2. Después de instanciar el objeto NPay, declarar e implementar la interfaz OnCatalogReceivedListener en la que se recibirán los items del catálogo. 3. Implementar el método OnCatalogReceived dentro de la definición anterior de OnCatalogReceivedListener, para procesar la información de los items. Este método recibe como parámetros dos valores: Int responsetype y Lis &LTPayCatalogItem&GT; result I. responsetype Indica la manera en que se obtuvieron los items; sus valores posibles son: NPayConstants.CATALOG_ITEMS: Items recibidos mediante la llamada de obtención del Catálogo. NPayConstants.PURCHASED_ITEMS: Items recibidos mediante la llamada de recuperación de compras previas. Se recomienda utilizar un condicional switch case para ejecutar las acciones deseadas dependiendo del tipo de llamada que se ejecutó. Ejemplo:

15 II. List&LT;NPayCatalogItem&GT; result Objeto List cuyos elementos son instancias del objeto NPayCatalogItem. Mediante los métodos públicos de este objeto (Véase sección Referencias) se podrá obtener la información del item. Se recomienda implementar un bucle para recorrer los items recibidos. Ejemplo: 4. Establecer el objeto definido de la interfaz OnCatalogReceivedListenera la instancia de NPay mediante el siguiente método: 5. Ejecutar el método getpurchasednonconsumableitems() para obtener las compras previas del consumidor. Se deberá colocar este método en cualquier acción que lo requiera. Ejemplo: MainActivity.java

16 C. Realizar Compra Para realizar una petición de compra, se deberá ejecutar el método NPay.requestPurchase(String sku) Para ello es necesario implementar los siguientes pasos: 1. Importar en el código las siguientes librerías: 2. Después de instanciar el objeto NPay, declarar e implementar la interfaz OnPurchaseDataListener en la que se recibirá la respuesta de la transacción de cobro. 3. Implementar el método onpurchasedatareceive dentro de la definición anterior de OnPurchaseDataListener, para procesar la respuesta de la transacción. Este método recibe como parámetro una instancia del objeto NPayResponseData. Mediante los métodos públicos de este objeto (Véase sección Referencias), se podrá obtener la información de la transacción. 4. Establecer el objeto definido de la interfaz OnPurchaseDataListener a la instancia de NPay mediante el siguiente método: 5. Ejecutar el método requestpurchase(string sku) para realizar una petición de compra. Este método recibe como parámetro el sku del item a cobrar. Puede establecerse manualmente en el código o ser obtenido de uno de los items recibidos en el Catálogo de Items de la aplicación.

17 Se deberá colocar este método en cualquier acción en la que se requiera realizar una petición de cobro Ejemplo: MainActivity.java

18 8. Referencias Existen dos objetos con diferentes métodos y cada uno de ellos con un valor específico: A. npaycatalogitem B. npaycatalogitem A. NPayCatalogItem Objeto que define a cada Item del Catálogo de la aplicación Métodos Tipo Valor getformattedbaseprice(); String Precio base en USD formateado, por ejemplo 2.00 USD getformattedlocalprice(); String Precio en moneda local formateado, por ejemplo 9.99 MXND getname(); String Nombre del item getdescription(); String Descripción del item ispurchased(); Boolean Indicador si el item ha sido adquirido (true false) isconsumable() Boolean Indicador si el item es consumible (true false) getid_item(); String ID único del item getsku(); String SKU del item geti_type(); int Tipo de item: 0 Consumible, 1 No consumible tostring(); String Cadena descriptora del objeto NPayCatalogItem

19 B. NPayResponseData Objeto que define la respuesta de una transacción de cobro. Métodos Tipo Valor getid_checkout(); String ID del checkout generado getid_trx(); String ID de la transacción generada getsku(); String SKU del item comprado getid_customer(); String ID del customer de npay getstatus(); String Status del checkout: "success" "failed" A. Definición 9. Consultar transacciones vía API Es posible consultar las transacciones realizadas a través de la Librería Android, mediante una consulta directa a la API REST denpay. Esto permite al desarrollador obtener el estado de una transacción mediante comunicación server to server. Para realizar una petición a la API, se requiere que la App tenga un sdk_key válido y el id_checkout que se desea consultar, éste último obtenido en la respuesta de la petición de compra en la Librería Android. A continuación se describe la forma en realizar la petición. Endpoint: Método Argumentos: sdk_keyid_checkout (En la URL de la petición)

20 Ejemplo de Respuesta: B. Códigos de respuesta Código Estado Descripción (Ejemplo) 200 OK SUCCESS 400 BAD REQUEST A mandatory parameter is missing, Parameter mistype (String instead of Integer) 401 UNAUTHORIZED The sdk_key doesn t exist, The sdk_key is missing, The sdk_key is expired, invalid or revoked 404 NOT FOUND The resource identifier is invalid 500 INTERNAL ERROR Unexpected behavior, Files corrupted, Frozen Platform 503 SERVICE UNAVAILABLE Scheduled maintenance in progress

21 10. FAQs Cómo obtener el SKU? El SKU es un identificador del ítem y podrá ser definido por el propio desarrollador al momento de dar de alta un item. Cómo obtener el sdk_key? El sdk_key se obtiene al momento de dar de alta una aplicación con compras inapp en la consola. Cómo agregar items? Los ítems se agregan desde la consola del desarrollador. Cómo identificar a un consumidor? Los consumidores podrán ser identificados a través de un Id de consumidor (id_customer) proporcionado por npay a través de la librería en las transacciones de cobro. Cómo efectuar un cobro? Para efectuar un cobro se deberá emplear el método: requestpurchase(string sku). Para conocer cómo implementar el método deberá referirse a la sección Realizar Compra de la documentación Cómo Obtener compras previas por un consumidor? Para obtener las compras previas de un consumidor se deberá emplear el método: getpurchasednonconsumableitems().para conocer cómo implementar el método deberá referirse a la sección Consultar Compras Previas de la documentación. Cómo identifico con que operadores telefónicos cobrar? Desde el sitio se podrán conocer a los operadores telefónicos con los que se puede realizar una transacción de cobro. Porque No aparece el dialogo de cobro? Si al ejecutar la transacción de cobro no se muestran los diálogos correspondientes, se deberá verificar la correcta implementación del método de transacción de cobro requestpurchase(srting sku). Para conocer cómo implementar el método deberá referirse a la sección Realizar Compra de la documentación. Porque no se puede obtener la lista de ítems? Se deberá verificar la correcta implementación del método de obtención de catálogo getcatalog().para conocer cómo implementar el método deberá referirse a la sección Obtener Catálogo de Items de la documentación. Porque no se obtuvo respuesta del cobro? Se deberá validar la correcta implementación del métodorequestpurchase(string sku). En algunos casos podría existir saturación por parte del operador telefónico por lo que se recomienda realizar una vez más la transacción.

22 11. Glosario npay npay es la plataforma de cobro de Naranya. Es un sistema procesador de pagos que permite a desarrolladores implementar el cobro vía operador telefónico. SDK Key Llave única generada por aplicación por el servidor cuando la App es creada por un desarrollador. Debe ser incluida en el archivo AndroidManifest.xml de la aplicación. Permite a la aplicación interactuar de manera segura con la Librería y la API de npay. Compra In-App (In-App Purchase) Funcionalidad de una aplicación que le permite ofertar a los consumidores una variedad de items adicionales directamente dentro de la aplicación. Item Cada uno de los productos o servicios que se configuran y ofertan como In-App Purchase. SKU SKU o Stock-keeping unit, (número de referencia) es un identificador usado en el comercio con el objeto de permitir el seguimiento sistémico de los productos y servicios ofrecidos a los clientes. Cada SKU se asocia con un objeto, producto, marca, servicio, cargos, etc. Item Consumible (Consumable Item) Son items de un uso o con un número máximo de usos y que desaparecen o pierden efecto una vez que se utilzan el número de veces que se ha definido. Pueden ser utilizados solamente si son adquiridos nuevamentey pueden ser acumulables. Por ejemplo vidas en un juego, pociones de recuperación, municiones, etc. Item No Consumible (Non Consumable Item) Son items sin un limite de uso o de uso permanente. Por ejemplo niveles en un juego, filtros fotográficos, personajes desbloqueables, etc. Catálogo de Items Es el conjunto de Items configurados en la aplicación y que pueden ser adquiridos por el consumidor. API Interfaz de programación de aplicaciones (IPA) o API (del inglés Application Programming Interface) es el conjunto de funciones y procedimientos (o métodos, en la programación orientada a objetos) que ofrece cierta biblioteca para ser utilizado por otro software como una capa de abstracción. REST REST, REpresentational State Transfer, es un tipo de arquitectura de desarrollo web que se apoya totalmente en el estándar HTTP. REST permite crear servicios y aplicaciones que pueden ser usadas por cualquier dispositivo o cliente que entienda HTTP, por lo que es más

23 simple y convencional que otras alternativas que se han usado en los últimos años como SOAP y XML-RPC.