SDK de iOS heredado

Nota

Esto se describe el SDK de iOS heredado, que solo funciona con versiones de Digital Assistant hasta la 19.4.1. Si dispone de una versión posterior de Digital Assistant, utilice el SDK iOS nativo de Oracle.

Con el SDK del cliente, puede integrar el asistente digital con aplicaciones iOS. La aptitud no se comunica con iOS directamente. En su lugar, un servidor de chat actúa como intermediario y se comunica con la aptitud a través de solicitudes HTTPS y con iOS a través de WebSockets. Las bibliotecas de cliente de SDK, cuando se despliegan en las aplicaciones nativas, establecen la conexión WebSocket con el manejador de mensajes adecuado.

Descripción de client_sdks-ios.png a continuación

Para esta clase de integración, cree un canal de iOS en Digital Assistant y, a continuación, copie el ID de aplicación generado en el código de aplicación del cliente.

Instalación del marco

Puede instalar el marco (que se encuentra en el archivo ZIP del SDK, en el directorio Bots.framework) en el proyecto de la aplicación de forma manual para el desarrollo y las pruebas, pero, para producción, tiene que distribuirlo de forma local a través de CocoaPods.

Instalación del marco de desarrollo y prueba

Utilice este método para probar el marco. No se puede enviar una aplicación a App Store si se agrega el marco de forma manual al proyecto.

Para agregar manualmente el marco al proyecto:

  1. Descargue el SDK de cliente de Digital Assistant para el módulo iOS desde la página de descarga de ODA y OMC de Oracle Technology Network y descomprímalo en la máquina local.

  2. Agregue el marco al proyecto Xcode seleccionando Archivo > Agregar archivos a My_Project y, a continuación, seleccionando Bots.framework en el selector de archivos.

  3. En la configuración del proyecto, agregue Bots.framework a la lista de binarios incrustados en el separador General del destino de la aplicación.

    Ya puede importar el marco (#import <Bots/Bots.h>) y empezar a utilizarlo en el código.

Instalación del marco de producción

Cuando la aplicación esté lista para la fase de producción, utilice CocoaPods para distribuir Bots.framework y la documentación de referencia de la API asociada. El Podspec se publica localmente como parte de un paquete de distribución.

Distribución del marco con un Podspec local

Puede distribuir el marco con un Podspec local. Después de descargar este archivo, los usuarios lo instalan con las herramientas de línea de comandos de CocoaPads.

Para publicar el Podspec local:

  1. Cree un archivo Podspec que defina estos atributos:
    • version
    • summary
    • homepage
    • license
    • author
  2. Cree un archivo ZIP que incluya el marco.
  3. Aloje el archivo ZIP en un servidor disponible para el proceso de generación.

Inicialización del SDK de cliente en la aplicación

Para que el código pueda llamar al SDK, antes tiene que inicializar la biblioteca utilizando el ID de aplicación generado para el bot al agregar un canal de iOS. Para obtener este ID, haga clic en Agregar canal para abrir el cuadro de diálogo Crear canal. Agregue un nombre para el canal de iOS y, a continuación, seleccione iOS como tipo de canal. Después de hacer clic en Crear, Digital Assistant genera el ID de aplicación. A continuación, utilice este ID para sustituir YOUR APP ID en el método applicationDidFinishLaunchingWithOptions::
  • Objective-C

    [Bots initWithSettings:[OMCSettings settingsWithAppId:@"YOUR_APP_ID"] completionHandler:^(NSError * _Nullable error, NSDictionary * _Nullable userInfo) {
        // Your code after init is complete
    }];
  • Swift:
    Bots.initWith(OMCSettings(appId: "YOUR_APP_ID")) { (error: Error?, userInfo: [AnyHashable : Any]?) in// Your code after init is complete}
Puede mostrar la interfaz de usuario de Digital Assistant en cualquier lugar de la aplicación, una vez finalizada la carga, agregando la línea siguiente:
  • Objective-C:
    [Bots show];
  • Swift:
    Bots.show();

Llamada a otras funciones

Puede llamar a otras funciones después de que el SDK se haya inicializado correctamente. Por ejemplo, puede actualizar el nombre, el apellido y la dirección de correo electrónico del usuario:
// Update first name and last name
   [Bots setUserFirstName:@"John"
           lastName:@"Smith"];

// Update email address
   [OMCUser currentUser].email = @"john.smith@example.com";

Actualización del SDK

Ejecute estas tareas para actualizar las dependencias Carthage:
$ carthage update

Agregar claves necesarias al info.plist de la aplicación

Es posible que el SDK de cliente de iOS tenga que pedir permiso a los usuarios para utilizar algunas funciones. Dependiendo de la función, tendrá que proporcionar una descripción en el Info.plist de la aplicación para explicar por qué necesita acceder. Estas descripciones se mostrarán cuando se solicite permiso al usuario.

Imágenes

El SDK de cliente para iOS permite a los usuarios enviar imágenes. Para dar soporte a esta función, tiene que proporcionar una descripción para las claves siguientes:
  • NSCameraUsageDescription: describe el motivo por el que la aplicación accede a la cámara (por ejemplo, se necesita permiso para acceder a la cámara para poder enviar imágenes a ${PRODUCT_NAME}). Para obtener más información, consulte la documentación de iOS sobre NSCameraUsageDescription.

  • NSPhotoLibraryUsageDescription: describe el motivo por el que la aplicación accede a la biblioteca de fotos (por ejemplo: se necesita permiso para acceder a la biblioteca de fotos para poder enviar imágenes a ${PRODUCT_NAME}). Para obtener más información, consulte la documentación de iOS sobre NSPhotoLibraryUsageDescription.

Nota

A partir de iOS 10, estos valores son necesarios. Si no están presentes en el Info.plist de la aplicación, no se mostrará la opción para enviar una imagen.

Ubicación

El SDK de cliente para iOS también permite a los usuarios enviar su ubicación actual. Para soportar esta función, debe proporcionar una descripción para cualquiera de las siguientes claves, en función del uso de los servicios de ubicación por parte de la aplicación. El SDK solicitará al usuario la ubicación en función de la clave que proporcione:
  • NSLocationWhenInUseUsageDescription: describe el motivo para que la aplicación acceda a información de la ubicación del usuario mientras se está utilizando la aplicación (por ejemplo: los servicios de ubicación son necesarios para enviar la ubicación actual a ${PRODUCT_NAME}). Se recomienda utilizar este permiso si la aplicación no utiliza servicios de ubicación. El SDK lo establecerá por defecto si se incluyen ambas claves. Consulte la documentación de iOS sobre NSLocationWhenInUseUsageDescription.

  • NSLocationAlwaysUsageDescription: describe el motivo para que la aplicación acceda a la información de ubicación del usuario en cualquier momento (por ejemplo: los servicios de ubicación son necesarios para enviar la ubicación actual a ${PRODUCT_NAME}). Consulte la documentación de iOS sobre NSLocationAlwaysUsageDescription.

Nota

Si no proporciona una de estas claves, cuando el usuario intente enviar su ubicación, no podrá hacerlo.

Importación del archivo de cabecera de bots

Importe el archivo de bots en el archivo .m del delegado de la aplicación .y en cualquier otro lugar donde vaya a utilizarlo.

  • Objective-C:
    #import <Bots/Bots.h>
  • Swift:
    import Bots

Localización de aplicaciones de iOS

Todas las cadenas que se ven en el bot se pueden personalizar y localizar. Digital Assistant proporciona algunos idiomas listos para usar, aunque agregar nuevos idiomas es fácil. Al localizar cadenas, Digital Assistant busca primero BotsLocalizable.strings en el grupo de aplicaciones y, a continuación, en el grupo de Digital Assistant, lo que le permite personalizar las cadenas y agregar soporte para otros idiomas.

Activación de la localización

Para que Digital Assistant pueda mostrar un idioma distinto del inglés, la aplicación tiene que activar en primer lugar el soporte para dicho idioma. Puede activar un segundo idioma en la configuración del proyecto Xcode:
Descripción de xcode_project_language_settings.png a continuación

Una vez hecho esto, Digital Assistant se mostrará en el idioma del dispositivo del idioma soportado.

Con el SDK de cliente de Digital Assistant para iOS, se incluyen los idiomas siguientes: árabe, inglés, finés, francés, alemán, italiano, japonés, coreano, chino mandarín (tradicional y simplificado), farsi, portugués (Brasil y Portugal), ruso, esloveno, español y sueco.
Nota

La localización está sujeta al almacenamiento en caché. Si no puede ver los cambios, le sugerimos limpiar el proyecto, restablecer el simulador o suprimir la aplicación de los dispositivos de prueba.

Personalización de cadenas

Digital Assistant permite personalizar las cadenas que muestra a través del mecanismo de localización de Apple. Para reemplazar una o más cadenas, agregue un archivo de cadenas vacío denominado BotsLocalizable.strings al proyecto Xcode y especifique nuevos valores para las claves que quiera reemplazar. Por ejemplo, para cambiar la cabecera “Messages” y el botón “Done”, cree un archivo con el contenido siguiente:
"Messages" = "My Messages"

"Done" = "I'm Done"
Para activar la personalización de cadenas en distintos idiomas, asegúrese de localizar el archivo BotsLocalizable.strings en Xcode.
Descripción de ios_localize.png a continuación

Archivo BotsLocalizable.strings

Este es el conjunto completo de claves:
/* Nav bar button, action sheet cancel button */
"Cancel" = "...";

/* Conversation title */
"Messages" = "...";

/* Conversation header. Uses CFBundleDisplayName */
"This is the start of your conversation with the %@ team. We'll stay in touch to help you get the most out of your app.\nFeel free to leave us a message about anything that’s on your mind. We’ll get back to your questions, suggestions or anything else as soon as we can." = "...";

/* Conversation header when there are previous messages */
"Show more..." = "...";

/* Conversation header when fetching previous messages */
"Retrieving history..." = "...";

/* Error message shown in conversation view */
"No Internet connection" = "...";

/* Error message shown in conversation view */
"Could not connect to server" = "...";

/* Error message shown in conversation view */
"An error occurred while processing your action. Please try again." = "...";

/* Error message shown in conversation view */
"Reconnecting..." = "...";

/* Fallback used by the in app notification when no message author name is found */
"%@ Team" = "...";

/* Conversation send button */
"Send" = "...";

/* Conversation text input place holder */
"Type a message..." = "...";

/* Conversation nav bar left button */
"Done" = "...";

/* Failure text for chat messages that fail to upload */
"Message not delivered. Tap to retry." = "...";

/* Status text for chat messages */
"Sending..." = "...";

/* Status text for sent chat messages */
"Delivered" = "...";

/* Status text for chat messages seen by the appMaker */
"Seen" = "...";

/* Timestamp text for recent messages */
"Just now" = "...";

/* Timestamp text for messages in the last hour */
"%.0fm ago" = "...";

/* Timestamp text for messages in the last day */
"%.0fh ago" = "...";

/* Timestamp text for messages in the last week */
"%.0fd ago" = "...";

/* Action sheet button label */
"Take Photo" = "...";

/* Action sheet button label */
"Use Last Photo Taken" = "...";

/* Action sheet button label */
"Choose from Library" = "...";

/* Photo confirmation alert title */
"Confirm Photo" = "...";

/* Action sheet button label */
"Resend" = "...";

/* Action sheet button label */
"View Image" = "...";

/* Error displayed in message bubble if image failed to download */
"Tap to reload image" = "...";

/* Error displayed as message if location sending fails */
"Could not send location" = "...";

/* Error title when user selects "use latest photo", but no photos exist */
"No Photos Found" = "...";

/* Error description when user selects "use latest photo", but no photos exist */
"Your photo library seems to be empty." = "...";

/* Error title when user attempts to upload a photo but Photos access is denied */
"Can't Access Photos" = "...";

/* Error description when user attempts to upload a photo but Photos access is denied */
"Make sure to allow photos access for this app in your privacy settings." = "...";

/* Error title when user attempts to take a photo but camera access is denied */
"Can't Access Camera" = "...";

/* Error description when user attempts to take a photo but camera access is denied */
"Make sure to allow camera access for this app in your privacy settings." = "...";

/* Generic error title when user attempts to upload an image and it fails for an unknown reason */
"Can't Retrieve Photo" = "...";

/* Generic error description when user attempts to upload an image and it fails for an unknown reason */
"Please try again or select a new photo." = "...";

/* Error title when user attempts to send the current location but location access is denied */
"Can't Access Location" = "...";

/* Error description when user attempts to send the current location but location access is denied */
"Make sure to allow location access for this app in your privacy settings." = "...";

/* UIAlertView button title to link to Settings app */
"Settings" = "...";

/* UIAlertView button title to dismiss */
"Dismiss" = "...";

/* Title for payment button */
"Pay Now" = "...";

/* Title for message action when payment completed */
"Payment Completed" = "...";

/*
 Instructions for entering credit card info. Parameters are as follows:
 1. Amount (e.g. 50.45)
 2. Currency (e.g. USD)
 3. App name (Uses CFBundleDisplayName)
*/
"Enter your credit card to send $%@ %@ securely to %@" = "...";

/* Error text when payment fails */
"An error occurred while processing the card. Please try again or use a different card." = "...";

/* Button label for saved credit card view */
"Change Credit Card" = "...";

/*
 Information label for saved credit card view. Parameters are as follows:
 1. Amount (e.g. 50.45)
 2. Currency (e.g. USD)
 3. App name (Uses CFBundleDisplayName)
 */
"You're about to send $%@ %@ securely to %@" = "...";

/* Title for user notification action */
"Reply" = "...";

/* Date format used for message grouping headers on the conversation screen */
"MMMM d, h:mm a" = "MMMM d, h:mm a";

/* Date format used for message timestamps on the conversation screen */
"hh:mm a" = "hh:mm a";

/* Error message when the content of a webview fails to load */
"Failed to open the page" = "...";

Aplicar estilo a la interfaz de conversación

El estilo de la interfaz de usuario de conversación se puede controlar mediante dos técnicas:
  • Utilizando el proxy UIAppearance de UINavigationBar para aplicar estilo al color y la apariencia de la barra de navegación.

  • La clase OMCSettings proporciona acceso a la barra de estado y al color de las burbujas de los mensajes.

Supongamos que desea que la interfaz de usuario de la conversación tenga una barra de navegación negra y burbujas de mensajes rojas. En primer lugar, utilice el proxy de apariencia de UINavigationBar para configurar la barra de navegación. A continuación, utilice OMCSettings para terminar de aplicar estilo a la interfaz de usuario:
  • Objective C
    OMCSettings* settings = [OMCSettings settingsWithAppId:@"YOUR_APP_ID"];
    settings.conversationAccentColor = [UIColor redColor];
    settings.conversationStatusBarStyle = UIStatusBarStyleLightContent;
    
    [[UINavigationBar appearance] setBarTintColor:[UIColor blackColor]];
    [[UINavigationBar appearance] setTintColor:[UIColor redColor]];
    [[UINavigationBar appearance] setTitleTextAttributes:@{ NSForegroundColorAttributeName : [UIColor redColor] }];
  • Swift
    var settings = OMCSettings(appId: "YOUR_APP_ID");
    settings.conversationAccentColor = UIColor.red();
    settings.conversationStatusBarStyle = UIStatusBarStyle.LightContent
    UINavigationBar.appearance().barTintColor = UIColor.black();
    UINavigationBar.appearance().tintColor = UIColor.red();
    UINavigationBar.appearance().titleTextAttributes = [ NSForegroundColorAttributeName : UIColor.red()];

Opciones de menú

El SDK de iOS incluye un menú que permite al usuario enviar varios tipos de mensajes.
Descripción de ios_menu_displayed.png a continuación

El SDK activa este menú por defecto, pero es posible ocultarlo o personalizar sus opciones.
Descripción de ios_menu_hidden.png a continuación

Para controlar la visualización del menú, sustituya la matriz allowedMenuItems de la clase OMCESettings. También puede agregar o eliminar opciones de menú.
// Init Bots Settings
OMCSettings* settings = [OMCSettings settingsWithAppId:appID];
 
 
// You can either disable all options by overwriting the settings with an empty array
settings.allowedMenuItems = nil;
 
 
// OR
// Specify the options accordingly - The options are Camera, Gallery, Document and Location
settings.allowedMenuItems = @[
                              OMCMenuItemCamera,   // Camera
                              OMCMenuItemGallery,  // Photo Gallery
                              OMCMenuItemDocument, // Upload Document
                              OMCMenuItemLocation  // Share Location
                            ];
 
// Then initialize the Bots client with the settings above
[Bots initWithSettings:settings
         completionHandler:^(NSError * _Nullable error, NSDictionary * _Nullable userInfo) {
        // Your code goes here
 
 
}];

Capacidades admitidas

Los canales de iOS en Digital Assistant admiten las siguientes capacidades:

  • texto (tanto envío como recepción)
  • imágenes (tanto envío como recepción)
  • archivos (tanto envío como recepción)
  • emojis (tanto envío como recepción)
  • ubicación (no se admite el envío, soporte completo para recepción)
  • enlaces
  • devoluciones
  • solicitudes de ubicación
  • propiedades personalizadas
  • componentes del carrusel
  • componentes de la lista

Restricciones de mensajes

Los canales de iOS en Digital Assistant tienen las siguientes restricciones de mensaje:

  • Mensajes de texto
    • Longitud máxima de la etiqueta de acción de texto: 128 caracteres
    • Tipos de acciones de texto permitidas: devolución, URL
    • Número máximo de acciones de texto: 6. Si hay más acciones de texto, el mensaje se convierte en varias tarjetas horizontales. En todas las tarjetas, se utiliza el mismo texto como título y cada una contiene hasta 6 acciones.
  • Tarjetas horizontales
    • Longitud máxima del título: 30 caracteres
    • Longitud máxima de la descripción: 128 caracteres
    • Longitud máxima de la etiqueta de acción de la tarjeta: 25 caracteres
    • Número máximo de tarjetas: 10
    • Número máximo de acciones de tarjeta: 3. Si hay más de 3 acciones de tarjeta, la tarjeta se duplica para presentar las acciones de tarjeta restantes.
    • Número mínimo de acciones de tarjeta: 1
    • ¿Se necesita al menos una descripción, imagen o acción?: no
    • Tipos de acciones de tarjeta permitidas: retroceso, URL
    • Tipos de acciones de lista de tarjetas permitidas: retroceso, URL
  • Tarjetas verticales
    • ¿Se admite?: no. El diseño de la tarjeta se convierte en horizontal.
  • Mensajes anexos
    • ¿Se admite?: sí
    • Tipos de acciones de anexo permitidas: retroceso, URL
  • Botones de acción
    • Longitud máxima de la etiqueta de acción global: 128 caracteres
    • Tipos de acciones globales permitidas: devolución, Ubicación

Extensiones de canal iOS

En los canales de iOS, puede ampliar la funcionalidad de los componentes System.CommonResponse con capacidades específicas del SDK de iOS.

Para acceder a las extensiones, utilice el elemento channelCustomProperties del componente System.CommonResponse y defina las propiedades adecuadas. El código tiene el formato siguiente:

...
            channelCustomProperties:
            - channel: "ios"
              properties:
                PROPERTY_NAME: "PROPERTY_VALUE"
...

A continuación, se muestran las propiedades personalizadas disponibles para los canales de iOS:

Nombre Valores permitidos Se aplica a... Descripción
mediaType
  • Un tipo de medio válido
  • Elementos de respuesta con los siguientes atributos:
    • type: "attachment"
    • attachmentType: "file"or attachmentType: "image"
  • Tarjetas con imageUrl especificado
Tipo de medio del anexo. Por ejemplo, image/jpeg. Si no se especifica, el tipo de medio se resuelve desde el URL del anexo.

Para obtener más información general sobre channelCustomProperties, consulte Extensiones específicas del canal.