Adición de MobileFirst Foundation SDK a aplicaciones Cordova

improve this page | report issue

Visión general

En esta guía de aprendizaje, aprenderá a añadir MobileFirst SDK a una aplicación Cordova nueva o existente creada con Apache Cordova, Ionic u otra herramienta de un tercero. También aprenderá a configurar MobileFirst Server para que reconozca la aplicación, y para encontrar información sobre los archivos de configuración de MobileFirst que se cambian en el proyecto.

MobileFirst Cordova SDK se proporciona como un conjunto de plugins de Cordova, que se registra en NPM.
Los plugins disponibles son:

  • cordova-plugin-mfp - El núcleo de SDK
  • cordova-plugin-mfp-push - Proporciona soporte de notificaciones push
  • cordova-plugin-mfp-jsonstore - Proporciona soporte JSONStore
  • cordova-plugin-mfp-fips - Solo Android. Proporciona soporte de FIPS
  • cordova-plugin-mfp-encrypt-utils - Solo iOS. Proporciona soporte para el cifrado y descifrado

Niveles de soporte

Los plugins de MobileFirst dan soporte a las siguientes versiones de plataforma Cordova:

  • cordova-ios: >= 4.1.1 y < 7.0
  • cordova-android: >= 6.1.2 y < 11.0
  • cordova-windows: >= 5.0.0 y < 8.0

Nota: La última versión de cordova-windows publicada tiene un error que generará una excepción durante el inicio de la aplicación. Apache Cordova ha solucionado el problema en el repositorio de desarrollo pero no se ha publicado todavía. Se le recomienda que utilice la versión de cordova-windows del repositorio maestro que contiene el arreglo. El siguiente es el mandato que se puede utilizar para añadir la plataforma cordova-windows de modo que tenga aplicado el arreglo.

cordova platform add https://github.com/apache/cordova-windows

Ir a:

Nota: La funcionalidad de compartición de la cadena de claves es obligatoria al ejecutar aplicaciones iOS en el simulador de iOS al utilizar Xcode 8. Necesitará habilitar esta funcionalidad de forma manual antes de compilar el proyecto Xcode.

Componentes de Cordova SDK

cordova-plugin-mfp

El plugin cordova-plugin-mfp es el plugin principal de MobileFirst para Cordova. Este plugin es necesario. Si instala cualquier otro plugin de MobileFirst, también se instala automáticamente el plugin cordova-plugin-mfp en el caso de que todavía no lo esté.

Los siguientes plugins de Cordova se instalan como dependencias de cordova-plugin-mfp:

  • cordova-plugin-device
  • cordova-plugin-dialogs
  • cordova-plugin-globalization
  • cordova-plugin-okhttp

cordova-plugin-mfp-jsonstore

El plugin de cordova-plugin-mfp-jsonstore habilita que su aplicación utilice JSONstore. Para obtener más información sobre JSONstore, consulte la guía de aprendizaje de JSONStore.

cordova-plugin-mfp-push

El plugin cordova-plugin-mfp-push proporciona los permisos necesarios para utilizar notificaciones push desde MobileFirst Server para aplicaciones Android. Se necesita una configuración adicional para utilizar notificaciones push. Para obtener más información sobre las notificaciones push, consulte la guía de aprendizaje de Notificaciones push.

cordova-plugin-mfp-fips

El plugin cordova-plugin-mfp-fips proporciona soporte FIPS 140-2 para la plataforma Android. Para obtener más información, consulte el apartado Soporte a FIPS 140-2.

cordova-plugin-mfp-encrypt-utils

El plugin cordova-plugin-mfp-encrypt-utils proporciona infraestructuras de cifrado OpenSSL para las aplicaciones Cordova con la plataforma iOS. Para obtener más información, consulte Habilitación de OpenSSL para Cordova iOS.

Requisitos previos:

Adición de Mobile Foundation Cordova SDK

Siga las instrucciones más abajo para añadir Mobile Foundation Cordova SDK a un proyecto nuevo o existente de Cordova, y regístrelo en MobileFirst Server.

Antes de empezar, asegúrese de que MobileFirst Server está en ejecución.
Si está utilizando un servidor instalado localmente: Desde una ventana de línea de mandatos, vaya a la carpeta del servidor y ejecute el mandato: ./run.sh.

Nota: Si está añadiendo el SDK a una aplicación existente de Cordova, el plugin sobrescribe el archivo MainActivity.java en Android y el archivo Main.m en iOS.

Adición del SDK

Considere la posibilidad de crear el proyecto mediante la plantilla de aplicación de MobileFirst Cordova. La plantilla añade las entradas de plugin específicas necesarias de MobileFirst al archivo config.xml del proyecto de Cordova y proporciona un archivo index.js específico de MobileFirst, listo para ser utilizado, y que está configurado para el desarrollo de aplicaciones de MobileFirst.

Nueva aplicación

  1. Cree un proyecto de Cordova: cordova create projectName applicationId applicationName --template cordova-template-mfp.
    Por ejemplo:

    cordova create Hello com.example.helloworld HelloWorld --template cordova-template-mfp
    
    • “Hello” es el nombre de la carpeta de la aplicación.
    • “com.example.helloworld” es el ID de la aplicación.
    • “HelloWorld” es el nombre de la aplicación.
    • –template modifica la aplicación con añadidos específicos de MobileFirst.

    El archivo index.js de la plantilla permite utilizar características de MobileFirst adicionales como, por ejemplo, la traducción de aplicación multilingüe y opciones de inicialización (consulte la documentación del usuario para obtener más información).

  2. Cambie al directorio raíz del proyecto Cordova: cd hello

  3. Añada una o más plataformas soportadas al proyecto Cordova mediante mandatos de la interfaz de línea de mandatos (CLI) de Cordova: cordova platform add ios|android|windows. Por ejemplo:

    cordova platform add ios
    

    Nota: Puesto que la aplicación se configuró mediante la plantilla MobileFirst, el plugin principal de Cordova MobileFirst se añadió de forma automática con la plataforma en el paso 3.

  4. Prepare los recursos de la aplicación ejecutando el mandato cordova prepare:

    cordova prepare
    

Aplicación existente

  1. Vaya a la raíz de su proyecto Cordova existente y añada el plugin de Cordova principal de MobileFirst:

    cordova plugin add cordova-plugin-mfp
    
  2. Vaya a la carpeta www\js y seleccione el archivo index.js.

  3. Añada la siguiente función:

    function wlCommonInit() {
    
    }
    

Los métodos de API de MobileFirst estarán disponibles después de que se haya cargado el SDK de cliente de MobileFirst. Se llama entonces a la función wlCommonInit.
Utilice esta función para llamar a los diversos métodos de API de MobileFirst.

Adición manual de un SDK

También ofrecemos la opción de instalar el plugin desde la vía de acceso local. cordova-plugin-mfp se puede descargar desde la consola de MFP e instalar en la aplicación cordova.

  1. En el panel de control de la consola del servidor de MFP, pulse Download Center => Pulse el separador SDK => Descargue el SDK de cordova.

  2. Vaya a la raíz de su proyecto Cordova existente y añada el plugin de Cordova principal de MobileFirst:

    cordova plugin add [path-to downloaded mfp cordova plugin]/mfp-cordova/plugins/cordova-plugin-mfp
    

Registro de la aplicación

  1. Abra la ventana de línea de mandatos y vaya a la raíz del proyecto Cordova.

  2. Registre la aplicación en MobileFirst Server:

    mfpdev app register
    

El mandato de CLI mfpdev app register primero se conecta a MobileFirst Server para registrar la aplicación y, a continuación, actualiza el archivo config.xml en la raíz del proyecto Cordova con metadatos que identifican a MobileFirst Server.

Cada plataforma se registra como una aplicación en MobileFirst Server.

Sugerencia: También es posible registrar aplicaciones desde MobileFirst Operations Console:

  1. Cargue MobileFirst Operations Console.
  2. Pulse el botón Nuevo junto a Aplicaciones para registrar una nueva aplicación y seguir las instrucciones en la pantalla.

Utilización del SDK

Los métodos de API de MobileFirst estarán disponibles después de que se haya cargado el SDK de cliente de MobileFirst. Se llama entonces a la función wlCommonInit.
Utilice esta función para llamar a los diversos métodos de API de MobileFirst.

Actualización de MobileFirst Cordova SDK

Para actualizar MobileFirst Cordova SDK con el último release, elimine el plugin cordova-plugin-mfp: ejecute el mandato cordova plugin remove cordova-plugin-mfp y, a continuación, ejecute el mandato cordova plugin add cordova-plugin-mfp para añadirlo de nuevo.

Los releases de SDK se pueden encontrar en el repositorio NPM de SDK.

Artefactos de MobileFirst Cordova SDK generados

config.xml

El archivo de configuración de Cordova es un archivo XML necesario que contiene metadatos de aplicación y que se almacena en el directorio raíz de la aplicación.
Después de que MobileFirst Cordova SDK se añada al proyecto, el archivo config.xml que genera Cordova recibe un conjunto de nuevos elementos que se identifican con el espacio de nombres mfp:. Los elementos añadidos contienen información relacionada con las características MobileFirst y MobileFirst Server.

Ejemplo de valores de MobileFirst añadidos al archivo config.xml

<?xml version='1.0'encoding='utf-8'?>
<widget id="..." xmlns:mfp="http://www.ibm.com/mobilefirst/cordova-plugin-mfp">
    <mfp:android>
        <mfp:sdkChecksum>3563350808</mfp:sdkChecksum>
        <mfp:appChecksum>0</mfp:appChecksum>
        <mfp:security>
            <mfp:testWebResourcesChecksum enabled="false" ignoreFileExtensions="png, jpg, jpeg, gif, mp4, mp3" />
        </mfp:security>
    </mfp:android>
    <mfp:windows>
        <mfp:sdkChecksum>3563350808</mfp:sdkChecksum>
       <mfp:windows10>
          <mfp:sdkChecksum>...</mfp:sdkChecksum>          
          <mfp:security>
             <mfp:testWebResourcesChecksum/>
          </mfp:security>
    </mfp:windows>
    <mfp:platformVersion>8.0.0.00-20151214-1255</mfp:platformVersion>
    <mfp:clientCustomInit enabled="false" />
    <mfp:server runtime="mfp" url="http://10.0.0.1:9080" />
    <mfp:directUpdateAuthenticityPublicKey>the-key</mfp:directUpdateAuthenticityPublicKey>
    <mfp:languagePreferences>en</mfp:languagePreferences>
</widget>
Elemento Descripción Configuración
widget Elemento raíz del documento config.xml. El elemento contiene dos atributos necesarios:
  • id: Nombre del paquete de aplicación que se especificó cuando se creó el proyecto Cordova. Si este valor se cambia manualmente después de se haya registrado la aplicación con MobileFirst Server, la aplicación se debe registrar de nuevo.
  • xmlns:mfp: Espacio de nombres XML del plugin MobileFirst.
mfp:platformVersion Necesario. Versión del producto con la que se desarrolló el la aplicación. Establecido de forma predeterminada. No se debe cambiar.
mfp:directUpdateAuthenticityPublicKey Opcional. Cuando se habilita la característica de autenticidad de Direct Update, el paquete Direct Update se firma digitalmente durante el despliegue. Después de que el cliente baje el paquete, se realiza una comprobación de seguridad para validar la autenticidad del paquete. El valor de serie es la clave pública que se utilizará para autenticar el archivo .zip de Direct Update. Configúrelo con el mandato mfpdev app config direct_update_authenticity_public_key key-value.
mfp:languagePreferences Opcional. Contiene una lista separada por comas de entornos locales para visualizar los mensajes del sistema. Configúrelo con el mandato mfpdev app config language_preferences key-value.
mfp:clientCustomInit Controla la forma en la que se llama al método WL.Client.init. De forma predeterminada, este valor se establece en false y se llama al método WL.Client.init de forma automática después de que se haya instalado el plugin MobileFirst. Establezca este valor en true para que el código del cliente controle de forma explícita al llamar a WL.Client.init. Editado manualmente. Los valores del atributo enabled son true o false.
mfp:server La información de conexión del servidor remoto predeterminado. La aplicación de cliente utiliza esta información para comunicarse con MobileFirst Server.
  • url: El valor de url especifica el protocolo, host y valores de puerto de MobileFirst Server que el cliente utilizará de forma predeterminada para conectarse al servidor.
  • runtime: El valor de tiempo de ejecución especifica el tiempo de ejecución de MobileFirst Server en el que se registró la aplicación. Para obtener más información sobre el tiempo de ejecución de MobileFirst, consulte la visión general de MobileFirst Server.
  • El valor del url de servidor se configura con el mandato mfpdev app config server.
  • El valor del tiempo de ejecución del servidor se establece con el mandato mfpdev app config runtime.
mfp:ios Este elemento contiene toda la configuración de la aplicación de cliente relacionada con MobileFirst en la plataforma iOS.
  • mfp:appChecksum
  • mfp:sdkChecksum
  • mfp:security
mfp:android Este elemento contiene toda la configuración de la aplicación de cliente relacionada con MobileFirst en la plataforma Android.
  • mfp:appChecksum
  • mfp:sdkChecksum
  • mfp:security
mfp:windows Este elemento contiene toda la configuración de la aplicación de cliente relacionada con MobileFirst en la plataforma Windows.
  • mfp:appChecksum
  • mfp:windowsphone8
  • mfp:windows8
  • mfp:windows10
mfp:windows8 Este elemento contiene toda la configuración de la aplicación de cliente relacionada con MobileFirst en las plataformas Windows 8.1.
  • mfp:sdkChecksum
  • mfp:security
mfp:windows10 Este elemento contiene toda la configuración de la aplicación de cliente relacionada con MobileFirst en las plataformas Windows 10.
  • mfp:sdkChecksum
  • mfp:security
mfp:windowsphone8 Este elemento contiene toda la configuración de la aplicación de cliente relacionada con MobileFirst en las plataformas Windows 8.1.
  • mfp:sdkChecksum
  • mfp:security
mfp:appChecksum Este valor es la suma de comprobación de los recursos web de la aplicación. Se calcula al ejecutar mfpdev app webupdate. No es configurable por parte del usuario. El valor de la suma de comprobación se actualiza cuando se ejecuta el mandato mfpdev app webupdate. Para obtener más detalles sobre el mandato mfpdev app webupdate, escriba mfpdev help app webupdate en su ventana de mandatos.
mfp:sdkChecksum Este valor es la suma de comprobación de MobileFirst Operations Console SDK que se utiliza para identificar niveles de SDK de MobileFirst. No es configurable por parte del usuario. Este valor se establece de forma predeterminada.
mfp:security Este elemento contiene la configuración específica de la plataforma de la aplicación de cliente para la seguridad de MobileFirst. Contiene
  • mfp:testWebResourcesChecksum
mfp:testWebResourcesChecksum Controla si la aplicación verifica la integridad de sus recursos web cada vez que empieza a ejecutarse en el dispositivo móvil. Atributos:
  • enabled: Los valores válidos son true y false. Si este atributo se establece en true, la aplicación calcula la suma de comprobación de sus recursos web y compara esta suma de comprobación con un valor que se almacenó la primera vez que se ejecutó la aplicación.
  • ignoreFileExtensions: Cálculo de suma de comprobación que puede tardar unos segundos, dependiendo del tamaño de los recursos web. Para hacerlo más rápido, puede proporcionar una lista de extensiones de archivo que se pueden ignorar en este cálculo. Este valor se ignora cuando el valor del atributo enabled es false.
  • El atributo enabled se establece con el mandato mfpdev app config android_security_test_web_resources_checksum key-value.
  • El atributo ignoreFileExtensions se establece con el mandato mfpdev app config android_security_ignore_file_extensions value.

Edición de los valores de MobileFirst en el archivo config.xml

Utilice MobileFirst CLI para editar los valores anteriores ejecutando el mandato:

mfpdev app config

Soporte de la plataforma del navegador Cordova

MobileFirst Platform admite ahora la plataforma de Cordova Browser con otras plataformas soportadas de Cordova Windows, Cordova Android, y Cordova iOS.

El uso plataforma de Cordova Browser con MobileFirst Platform (MFP) es similar al de MFP con otras plataformas. Más adelante se expone un ejemplo para ilustrar esta característica.

Cree una aplicación de cordova mediante el siguiente mandato:

cordova create <your-appFolder-name> <package-name>

Esto creará una aplicación vanilla cordova.

Añada el plugin MFP mediante el siguiente mandato:

cordova plugin add cordova-plugin-mfp

Añada un botón que pueda servir para hacer ping a su servidor MFP (podría ser su servidor alojado localmente o un servidor en IBM Cloud). Haga ping a su servidor MFP haciendo clic en el botón. Puede utilizar el siguiente código de ejemplo:

index.html

<!DOCTYPE html>
<html>

<head>
   <meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
  <meta name="format-detection" content="telephone=no">
  <meta name="msapplication-tap-highlight" content="no">
  <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width">


  <link rel="stylesheet" type="text/css" href="css/index.css" />

  <!-- load script with wlCommonInit defined before loading cordova.js -->
  <script type="text/javascript" src="js/index.js"></script>
  <script type="text/javascript" src="cordova.js"></script>

  <title>Iniciador de MFP: Cordova</title>
</head>

<body>

  <div id="main">
    <div id="main_title">Hello MobileFirst</div>
    <div id="main_status"></div>
    <div id="main_info"></div>
  </div>

  <div id="button_content">
    <button id="ping_button" style="display:none">Haga ping al servidor de MobileFirst</button>
  </div>

</body>

</html>

index.js


var Messages = {
  // Add here your messages for the default language.
  // Generate a similar file with a language suffix containing the translated messages.
  // key1 : message1,
};

var wlInitOptions = {
  // Options to initialize with the WL.Client object.
  // For initialization options please refer to IBM MobileFirst Platform Foundation Knowledge Center.
   mfpContextRoot : '/mfp', // "mfp" is the default context root in the MobileFirst Development server
    applicationId : 'io.cordova.hellocordova' // Replace with your own app id/package name.
};

function wlCommonInit() {
  app.init();
}

var app = {
  //initialize app
  "init": function init() {
    var buttonElement = document.getElementById("ping_button");
    buttonElement.style.display = "block";
    buttonElement.addEventListener('click', app.testServerConnection, false);
  },
  //test server connection
  "testServerConnection": function testServerConnection() {

    var titleText = document.getElementById("main_title");
    var statusText = document.getElementById("main_status");
    var infoText = document.getElementById("main_info");
    titleText.innerHTML = "Hello MobileFirst";
    statusText.innerHTML = "Connecting to Server...";
    infoText.innerHTML = "";

    WLAuthorizationManager.obtainAccessToken()
      .then(
        function (accessToken) {
          titleText.innerHTML = "Yay!";
          statusText.innerHTML = "Connected to MobileFirst Server";
        },
        function (error) {
          titleText.innerHTML = "Bummer...";
          statusText.innerHTML = "Failed to connect to MobileFirst Server";
        }
        );
    },
 }

Nota: Es importante mencionar el mfpContextRoot y applicationId en el archivo wlInitOptions in index.js.

index.css

cuerpo {
    position: static;
    font-family: "HelveticaNeue-Light", "Helvetica Neue Light", "Helvetica Neue", Helvetica, Arial, "Lucida Grande", sans-serif;
    font-weight: 300;
    margin: 0px;
	padding: 0px;
}

#button_content {
  position: absolute;
  bottom: 10%;
  width: 100%;
}

#ping_button {
  display: block;
  margin: 0 auto;
  height: 50px;
  width: 240px;
  font-size: 20px;
  color: white;
  background-color: #325c80;
}

#main {
  top: 10%;
  position: absolute;
  text-align: center;
  width: 100%
}

#main_title {
  font-size: 40px;
}

#main_status {
  font-size: 20px;
  margin-top: 10px;
}

#main_info {
  font-size: 14px;
  margin-top: 10px;
}

Añada la plataforma del navegador mediante el siguiente mandato:

cordova platform add browser

Para registrar manualmente su aplicación:

  • Inicie sesión en la consola de su servidor MFP server.
  • Pulse el botón Nuevo junto a la opción *Aplicaciones*.
  • Proporcione un nombre a su aplicación, seleccione Web como la plataforma y proporcione su ID de la aplicación (que está definido en la función wlInitOptions de su index.js).

Recuerde: Añada los detalles del servidor en el config.xml de su aplicación.

Nota: el mfpdev-cli para registrar la aplicación de la plataforma se publicará pronto.

Después, ejecute los siguientes mandatos:

cordova prepare
cordova build
cordova run

Esto inicia un navegador que se ejecuta en un servidor proxy (en el puerto 9081) y conecta a un servidor MFP. El servidor proxy predeterminado del navegador cordova (que se ejecuta en el puerto 8000) se ha suprimido porque no puede conectarse al servidor MFP debido a la política del mismo origen.

El navegador predeterminado de ejecución está establecido en el Chrome. Utilice la siguiente opción--target para la ejecución en distintos navegadores y podrá utilizarlo mediante el siguiente mandato:

 cordova run --target=Firefox

La aplicación puede previsualizarse mediante el siguiente mandato:

mfpdev app preview

La única opción de navegador admitida es Representación de navegador simple. La opción Soporte del navegador móvil no está soportada para la plataforma del navegador no está soportada para la plataforma del navegador.

Uso de WebSphere Liberty para dar servicio a los recursos del navegador cordova

Siga la instrucción para utilizar WebSphere Liberty en este tutorial y realice los cambios siguientes.

Añada los contenidos de la carpeta del proyecto del navegador www a la aplicación web [MyWebApp] → src → Main → webapp tal como se menciona en el Paso 1 de la sección Compilación de la aplicación web Maven con los recursos de la aplicación web de este tutorial. Finalmente, registre su aplicación en el servidor Liberty y realice una prueba ejecutándolo en el navegador con la vía de acceso localhost:9080/MyWebApp. Añada también las carpetas sjcl y jssha a su carpeta padre y cambie su referencia en el archivo ibmmfpf.js.

Guías de aprendizaje con las que continuar

Con MobileFirst Cordova SDK ahora integrado, podrá:

Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on January 31, 2022