Sobre este documento

Este documento tiene el objetivo de describir el procedimiento a seguir a la hora de realizar la integración SDK SIGNply Android.

Introducción

Manual para la integración del SDK SIGNply Android. Por medio de este SDK podrá añadir la funcionalidad de firmar un fichero PDF sin apenas esfuerzo. En el presente documento se incluye el manual de integración del SDK para perfiles técnicos.

Contenido

  • SDK: Se facilita el SDK por medio del fichero SignplySDK.aar compatible con dispositivos físicos y con algunos simuladores modernos (ej. en Pixel 3 API 28).
  • Licencia: Se facilita un archivo de licencia para poder utilizar el SDK.
  • Manual de integración: Hace referencia a este documento.
  • Proyecto de ejemplo Swift: Ejemplo completo escrito en Kotlin de llamada al SDK de SIGNply para poder facilitar la integración. Puede servir cómo un punto de entrada para el proyecto a desarrollar. Contiene una licencia demo.
  • Proyecto de ejemplo simple Java: Ejemplo simple escrito en Java de llamada al SDK de SIGNply para poder facilitar la integración. Puede servir cómo un punto de entrada para el proyecto a desarrollar. Contiene una licencia demo.
  •  

Requisitos previos

Este SDK es compatible desde la versión de Android 6 (API 23) tanto con dispositivos físicos (smartphones y tablets) y algunos simuladores modernos. Es necesario establecer la versión mínima 23 en el build.gradle módulo app. Compila con la versión recomendada por Android en este momento (29). La versión de Android Studio utilizada es la 4.0.

Para una correcta compilación en simuladores es necesario añadir abiFilters “arm64-v8a” y “armeabi-v7a”. Se muestra en la imagen inferior.

Añadir el SDK es muy sencillo desde Android Studio:

File -> New Module -> Import .JAR / .AAR Package -> (seleccionar SignplySDK_0.1.0.beta.aar).

A continuación para asegurarse de que el SDK se ha añadido correctamente es necesario comprobar que la carpeta SignplySDK se encuentra dentro de los archivos en la pestaña Project.

Dentro de las dependencias del proyecto build.gradle (módulo app) es necesario añadir las siguientes líneas y sincronizar el proyecto.

implementation project(':SignplySDK')
implementation 'androidx.appcompat:appcompat:1.2.0' //SDK
implementation 'androidx.core:core-ktx:1.3.2' //SDK
implementation 'com.google.android.material:material:1.2.1' //SDK
implementation 'androidx.constraintlayout:constraintlayout:2.0.1' //SDK
implementation project(':SignplySDK')
implementation 'com.google.android.gms:play-services-location:17.1.0' //SDK
implementation 'commons-io:commons-io:2.6' //SDK

Utilización

El SDK de SIGNply es lanzado a través de un Intent, a este Intent es necesario pasarle un objeto de tipo SignplySDKParams.

val intent = Intent(this, SignplySDKLauncher::class.java) 
intent.putExtra("signplySDKParams", signplySDKParams)
startActivityForResult(intent, REQUEST_CODE_LAUNCH_SIGNPLY_SDK)

El resultado se obtiene en el onActivityResult. En el caso de que el documento se haya firmado correctamente devuelve una Uri con el documento firmado.
En caso contrario, devuelve un extra del Intent con la clave error y el error correspondiente como valor.

Parámetros principales de llamada

SIGNply dispone de una serie de parámetros de llamada para la configuración del firmado de documento que se exponen a continuación:

signplySDKParams (SignplySDKParams): estructura de datos que incluye toda la configuración necesaria.

Parámetros de SIGNply

Para facilitar la integración, la mayoría de parámetros son opcionales. El objeto SingplySDKParams se puede formar tan solo con esta mínima configuración en Kotlin.

val signplySDKParams = SignplySDKParams(license, selectedFileUri)

Licencia de tipo String, y selectectedFileUri de tipo Uri.
A continuación se muestran todos los parámetros disponibles y configurables.

  • SignplySDKParams

    • licenseB64 (String) : licencia en base 64 de ESS
    • uri (Uri): Uri del documento pdf.
    • saveDocumentSignedName (String): nombre de documento firmado. Si nó se especifica, por defecto obtiene el valor “documento_firmado.pdf” y lo guarda en la carpeta propia de la aplicación. Si el nombre ya existe se concatena un (1), (2), (3) y así sucesivamente
    • isPrivate (Boolean): Indica si el documento se debe guardar de manera privada para que no puedan acceder otras apps al documento firmado getFilesDir() o en caso contrario para ser accesibles desde otras apps getExternalFilesDir().
      *Los documentos se eliminan cuando se desinstala la aplicación. Ver más en:
      https://developer.android.com/training/data-storage
    • widget (SignplySDKWidget): widget de firma configurable
    • tsp (SignplySDKTSP): TSP configurable
    • header (SignplySDKHeader): parámetros de la cabecera de la firma
    • extra (SignplySDKExtra): funcionalidad extra en el SDK configurable
    • certificate (SignplySDKCertificate): certificado de firma configurable
  • SignplySDKWidget

    • widgetType (SignplySDKWidgetType): tipo de posicionamiento del widget
    • widgetFloatText (String): indica la cadena a buscar dentro del documento dónde se incrusta el widget. Devuelve el primer resultado obtenido. Este parámetro es sensible a mayúsculas y a minúsculas.
    • widgetFieldFieldname (String): nombre de campo preexistente en el que se incrusta el widget.
    • widgetManualRatio (Float): relación entre el ancho y el alto de widget para el posicionamiento manual. Por defecto 2,5. El valor debe estar entre 1 y 4. Si es menor que 1, toma valor 1 y si es mayor de 4 toma valor 4.
    • widgetFixedPage (Int): número de página en el que se incrusta el widget. Empieza en 1.
      Si el valor es 0 firma en todas las páginas.
      Si el valor es mayor que el número total de páginas se firma en la última página.
    • widgetFixedX (Int): indica el desplazamiento en horizontal de la posición del widget desde el vértice inferior izquierdo de la página de un documento.
    • widgetFixedY (Int): indica el desplazamiento en vertical de la posición del widget desde el vértice inferior izquierdo de la página de un documento.
    • widgetFloatGapY (Int): indica el número entero de unidades de desfase (positivo o negativo) en vertical desde la parte inferior al texto
    • widgetFloatGapX (Int): indica el número entero de unidades de desfase (positivo o negativo) en horizontal desde la parte inferior al texto
    • widgetCustomText (String): indica la cadena a incrustar en el widget de firma
    • widgetWidth (Int): ancho del widget. Valores entre [50 y 595]
    • widgetHeight (Int): alto del widget. Valores entre [50 y 842]

  • SignplySDKTSP

    • tspActivate (Bool): activación de introducción de sello de tiempo
    • tspURL (String): url de TSP
    • tspUser (String): usuario de TSP
    • tspPasswordB64 (String): password de TSP en base64

  • SignplySDKHeader

    • author (String): Autor de la firma
    • reason (String): Razón de la firma
    • contact (String): Contacto del autor o entidad de la firma
    • location (String): Localización del autor o entidad de la firma

  • SignplySDKExtra

    • autoOpen (Boolean): Permite desplegar el widget de firma automáticamente al abrir el documento. (viewLastPage debe ser false).
    • captureSignatureSeconds (Int): Tiempo previo a que se cierre el widget de firma
    • viewLastPage (Bool): Si es true, es necesario que el usuario visualice hasta la última página para poder firmar
  • SignplySDKCertificate

    • signCertP12B64 (String): Certificado de firma en base64
    • signCertPasswordB64 (String): Contraseña del certificado de firma en base64
    • encKeyB64 (String): Clave de codificación del certificado de firma en base64

  • SignplySDKWidgetType

    • manual: Posicionamiento modo manual en el cual el usuario puede mover la firma libremente.
    • field: Posicionamiento que busca un campo de firma en concreto.
    • fixed: Posicionamiento fijo en el documento, se le pasa un número de página y una posición relativa dentro del documento.
    • float: Posicionamiento flotante en el documento en base a una búsqueda de cadena de texto.

Resultados de SIGNply

El resultado se obtiene en el onActivityResult. En el caso de que el documento se haya firmado correctamente devuelve una Uri con el documento firmado.
En caso contrario, devuelve un extra del Intent con la clave error y el error correspondiente como valor.

https://developer.android.com/training/basics/intents/result?hl=es-419

Anotaciones

Los documentos que se hayan guardado y que no sean privados se pueden visualizar desde la carpeta de aplicación. Para ello es necesario acceder a la siguiente carpeta: Dentro del Almacenamiento es necesario ir a Android -> data -> (identificador de la aplicación) -> files

En esta carpeta se encuentran todos los ficheros PDF que hayan sido firmados desde el SDK de SIGNply.

Permisos

El SDK no declara permisos explícitos en el manifiesto (AndroidManifest.xml).
Para que funcione el TSP (Sellado de Tiempo) correctamente es necesario añadir el siguiente permiso desde el archivo de manifiesto de la aplicación dado que se necesita acceso a Internet:

<uses-permission android:name="android.permission.INTERNET" />

Si es necesario recoger la ubicación del usuario en el momento de la firma será necesario añadir el siguiente permiso en el manifiesto de la aplicación:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

En el caso de que se declare, si el usuario no ha concedido todavía el permiso de ubicación, se le requerirá en tiempo de ejecución cuando abra la caja de firma.

Estilos

El SDK usa los recursos de colores preestablecidos en el ecosistema Android. Estos pueden ser sobreescritos desde la aplicación. Desde styles.xml y colors.xml se pueden establecer los colores principales de un tema.

    • colorPrimary
    • colorPrimaryDark
    • colorAccent

https://developer.android.com/guide/topics/ui/look-and-feel/themes

  • Share: