Documentazione di Oracle Cloud Infrastructure

Messaggi Apple supportati per funzioni aziendali

Per le competenze che esponi tramite i canali Apple Messages for Business in Oracle Digital Assistant, puoi utilizzare funzionalità specifiche di Apple Messages for Business oltre alle funzionalità generalmente supportate su altri canali.

A tale scopo, in genere si utilizza l'elemento channelCustomProperties nei componenti di risposta comune per inserire proprietà specifiche di Apple.

Il codice ha il formato seguente:

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

Rich Link

Per incorporare i messaggi Rich Link nei canali Apple Messages for Business, utilizzare la proprietà personalizzata del canale richLinkData e la relativa proprietà secondaria assets. La proprietà assets può assumere un oggetto image o video, come mostrato in questo esempio: 

channelCustomProperties:
  - channel: "apple"
    properties:
      richLinkData:
        assets:
          image:
            data: "<base-64-encoded image data>"
            mimeType: "image/jpeg"
          video:
            mimeType: "video/mp4",
            url: "https://example.com/example.mov"

Esempio: Rich Link Image

responseItems:
  - type: "text"
    text: "iPad Pro"
    actions:
      - type: "url"
        url: "https://www.apple.com/ipad-pro/"
    channelCustomProperties:
      - channel: "apple"
        properties:
          richLinkData:
            assets:
              image:
                data: "<base 64 encoded image data>"
                mimeType: "image/jpeg"

Esempio: Rich Link Video

responseItems:
  - type: "text"
    text: "HomePod"
    actions:
    - type: "url"
      url: "https://images.apple.com/media/films/expand/homepod-expand-tpl-cc-us-20180306_1280x720h.mp4"
    channelCustomProperties:
    - channel: "apple"
      properties:
         richLinkData:
            assets:
              image:
                data: "<base 64 encoded image data>"
                mimeType: "image/jpeg"
              video:
                mimeType: "video/mp4",
                url: "https://store.storevideos.cdn-apple.com/v1/store.apple.com/st/1619042871000/mx532-

Risposta rapida

Il tipo di messaggio Risposta rapida è una convenzione utilizzata in Messaggi di Apple per Business per fornire da due a cinque risposte predefinite che un utente può selezionare con un solo tocco.

È possibile impostare il testo di riepilogo della risposta rapida utilizzando la proprietà personalizzata del canale summaryText: 

channelCustomProperties:
  - channel: apple
    properties:
      summaryText: Your selection

Se non si fornisce la proprietà summaryText, il canale utilizza invece la proprietà text.

Inoltre, tenere presente quanto segue:

  • summaryText non deve superare i 25 caratteri.
  • Per le parole chiave, utilizzare A, B, C, D e E (anziché i numeri).

Esempio: risposta rapida

responseItems:
  - text: "You can type or select from the options below:"
    type: text
    actions:
      - payload:
          variables:
            menuAction: orderAccessories
          action: orderAccessories
        label: "Order Accessories"
        type: postback
        keyword: "A"
      - payload:
          variables:
            menuAction: checkOrder
          action: checkOrder
        label: "Check Order Status"
        type: postback
        keyword: "B"
    channelCustomProperties:
      - channel: apple
        properties:
          summaryText: Your selection

Selettore elenco

I messaggi Apple per business hanno un tipo di messaggio selettore elenco che è possibile utilizzare per consentire agli utenti di selezionare una o più opzioni. Per incorporare i messaggi List Picker nei canali Apple Messages for Business, si utilizzano le seguenti proprietà personalizzate del canale Apple:

  • images. Questa è una lista di oggetti utilizzati dalle proprietà receivedMessage e replyMessage e che contengono gli elementi riportati di seguito.
    • identifier: l'identificativo in base al quale altre proprietà fanno riferimento all'immagine.
    • imageUrl: l'URL dell'immagine da visualizzare.
    • description.
  • receivedMessage. Si tratta di un oggetto con i seguenti elementi facoltativi:
    • imageIdentifier. Il relativo valore deve corrispondere alla proprietà identifier di una delle immagini definite nella proprietà personalizzata images.
    • style. I valori possibili sono icon, small e large.
    • subtitle.
    • title.
  • replyMessage. Si tratta di un oggetto con i seguenti elementi facoltativi:
    • imageIdentifier. Il relativo valore deve corrispondere alla proprietà identifier di una delle immagini definite nella proprietà personalizzata images.
    • style. I valori possibili sono icon, small e large.
    • subtitle.
    • title.
  • imageIdentifier. È possibile utilizzare questa proprietà all'interno dell'elemento channelCustomProperties dell'elemento options per aggiungere immagini alle opzioni nel selettore. Il relativo valore deve corrispondere alla proprietà identifier di una delle immagini definite nella proprietà personalizzata images.

È possibile creare selettori elenco a selezione singola utilizzando i tipi di elemento di risposta cards o editForm.

Per i selettori elenco a selezione singola che utilizzano editForm:

  • Impostare displayType per gli elementi su "singleSelect".

Per i selettori elenco a scelta multipla, utilizzare il tipo di elemento di risposta editForm:

  • Impostare displayType per gli elementi su "multiSelect".

È inoltre possibile creare selettori elenco con più sezioni utilizzando qualsiasi combinazione di elenchi singleSelect e multiSelect. A tale scopo, creare una voce nel file items per ogni sezione e impostare il file displayType di ogni voce su "singleSelect" o "multiSelect", a seconda del tipo di elenco desiderato per tale sezione.

Esempio: selettore elenco a selezione singola che utilizza schede

responseItems:         
  - type: "cards"
    cardLayout: "horizontal"
    headerText: "Here are our pizzas you can order today:"
    visible:
      entitiesToResolve:
        include: "Type"
    cards:
      - title: "${enumValue}"
        description: ""
        imageUrl: "system.entityToResolve.value.image"
        iteratorVariable: "system.entityToResolve.value.enumValues"
        actions:
          - label: "Order Now"
            type: "postback"
            payload:
              variables:
                pizza: "${enumValue}"
    channelCustomProperties: 
      - channel: "apple"
        properties:
          images:
            - identifier: image1
              imageUrl: "https://example.com/url1.jpg"
            - identifier: image2
              imageUrl: "https://example.com/url2.jpg"
          receivedMessage:
            imageIdentifier: "image1"
            style: "small"
            subtitle: "Fresh baked for you"
            title: "Select Your Pizza"
          replyMessage:
            title: "Selected Pizza"
            style: "small"
            imageIdentifier: "image2"

Esempi: selezione singola ListPicker mediante editForm

responseItems:
  - headerText: "Let's start Shopping!"
    type: editForm
    formColumns: 1
    items:
      - displayType: singleSelect
        name: selectHeadset
        options:
          - label: "Logitech® G435 LIGHTSPEED Wireless Gaming Headset"
            value: LogitechG435
            channelCustomProperties:
              - channel: apple
                properties:
                    imageIdentifier: logitech g435
          - label: "JBL Live 660NC Wireless Over-Ear NC Headphones"
            value: JBL660NC
            channelCustomProperties:
              - channel: apple
                properties:
                    imageIdentifier: jbl 660nc
          - label: "Altec Lansing® 3-In-1, MZX4100-PGRN-STK-6"
            value: altec
            channelCustomProperties:
              - channel: apple
                properties:
                    imageIdentifier: altec
        label: Select the headset of your choice
        placeholder: Tap to select the product
        channelCustomProperties:
          - channel: apple
            properties:
                subtitle: Headset of your choice
        required: true
    actions:
      - processingMethod: mapVariable
        variable: skill.skillSelectedProduct
        label: Submit
        type: submitForm
    channelCustomProperties:
      - channel: apple
        properties:
            showSummary: true
            receivedMessage:
              imageIdentifier: main
              subtitle: Personalized search on basis of your requirements
              style: large
              title: "Tap & Select Headphones"
            images:
              - identifier: main
                imageUrl: "https://example.com/b/shopping-cart-headphones-23724543.jpg"
              - identifier: logitech g435
                imageUrl: "https://example.com/60_o01_040122/2310460.jpg"
                description: "Play never ends with G435."
              - identifier: jbl 660nc
                imageUrl: "https://example.com/7693360_o01/7693360.jpg"
                description: "Enjoy while studying or working out."
              - identifier: altec
                imageUrl: "https://example.com/18_o01_110422/5159518.jpg"
                description: "Simple setup."
            replyMessage:
              imageIdentifier: logitech g435
              subtitle: "Your cart is ready!"
              style: icon
              title: Tap to view your response.

ListPicker (selezione multipla)

responseItems:
  - headerText: Choose the type of product you are looking
    type: editForm
    formColumns: 1
    items:
      - displayType: multiSelect
        name: features
        options:
          - label: Noise cancellation
            value: Noise cancellation
          - label: Microphone/Remote
            value: Microphone/Remote
          - label: Wireless
            value: Wireless
          - label: USB connectivity
            value: USB connectivity
          - label: Voice Assistant Support
            value: Voice Assistant Support
          - label: Fast Charging
            value: Fast Charging
        label: What features are you looking for?
        placeholder: Select multiple-values
        required: true
      - displayType: multiSelect
        name: usage
        options:
          - label: Attending Online Meetings
            value: Attending Online Meetings
          - label: Music
            value: Music
          - label: Casual usage
            value: Casual usage
          - label: Binge Watching
            value: Binge Watching
          - label: Jogging/Gym
            value: Jogging/Gym
        label: Your purpose of usage
        placeholder: Select multiple-values
        required: true
    actions:
      - processingMethod: mapVariable
        variable: requirementMap
        label: Submit
        type: submitForm
    channelCustomProperties:
      - channel: apple
        properties:
            receivedMessage:
              imageIdentifier: main
              subtitle: "Customize your product search!"
              style: icon
              title: "Tap & Provide your Preferences"
            images:
              - identifier: main
                imageUrl: "https://example.com/images/search-filter-icon.jpg"
              - identifier: filter
                imageUrl: "https://example.com/images/filter.jpg"
            replyMessage:
              imageIdentifier: filter
              style: icon

Selettore ora

Utilizzare il tipo di messaggio Selettore tempo in Messaggi mele per business per offrire agli utenti intervalli di tempo. Ogni elemento di campo timePicker nel editForm corrisponde a un intervallo di tempo che l'utente può selezionare. La proprietà defaultValue consente di impostare l'ora di inizio e la proprietà personalizzata del canale Apple duration per impostare la durata dell'intervallo di tempo in secondi. Esistono anche proprietà personalizzate del canale Apple per timeZoneOffset e location.

Esempio: selettore ora

responseItems:
  - headerText: "Select Date & Time for your appointment"
    type: editForm
    formColumns: 2
    items:
      - displayType: timePicker
        defaultValue: "2023-05-10T06:00Z"
        name: 27JanOne
        label: Slots available
        channelCustomProperties:
          - channel: apple
            properties:
              duration: 1800
        required: true
      - displayType: timePicker
        defaultValue: "2023-05-05T07:30Z"
        name: 27JanTwo
        label: Enter Time
        channelCustomProperties:
          - channel: apple
            properties:
              duration: 1800
        required: true
      - displayType: timePicker
        defaultValue: "2023-05-11T07:30Z"
        name: 24th
        label: another time
        channelCustomProperties:
          - channel: apple
            properties:
              duration: 1800
        required: true
    actions:
      - label: Submit
        type: submitForm
    channelCustomProperties:
      - channel: apple
        properties:
            receivedMessage:
              imageIdentifier: clock
              subtitle: "Every slot is of 30 mins.!"
              style: large
              title: "Tap & Select from available Slots"
            images:
              - identifier: clock
                imageUrl: "https://example.com/images/clock.png"
                description: clock
            timezoneOffset: 1200
            replyMessage:
              imageIdentifier: clock
              style: icon
              title: Selected Slot
            location:
              latitude: 28.605354
              radius: 1.5
              title: Supremo Customer Service Center
              longitude: 77.053546

Modulo Apple

È possibile creare messaggi di modulo Apple utilizzando il tipo di elemento di risposta editForm con una combinazione dei seguenti tipi di campo:

  • numberInput
  • textInput
  • datePicker
  • timePicker
  • singleSelect
  • multiSelect

Oltre alle proprietà del canale personalizzato necessarie per i vari campi del modulo, per l'intero modulo vengono utilizzate le seguenti proprietà personalizzate del canale Apple:

  • submitForm, impostato su true per l'ultimo elemento del modulo.
  • pickerTitle, che è possibile utilizzare facoltativamente per impostare il testo visualizzato in un determinato campo di testo del selettore.
  • selectedItemIndex, che è possibile utilizzare facoltativamente per impostare il numero di indice dell'elemento che si desidera selezionare per impostazione predefinita. L'impostazione predefinita è 0.

Definire una pagina di benvenuto per il form con la proprietà personalizzata del canale Apple splash. La proprietà splash contiene gli elementi riportati di seguito.

  • header.
  • splashText.
  • buttonTitle. Testo visualizzato sul pulsante. Obbligatorio.
  • imageIdentifier.

Esempio: modulo Apple

responseItems:
  - headerText: Provide Delivery Address details
    type: editForm
    formColumns: 1
    items:
      - displayType: textInput
        name: house_address
        label: House No.
        required: true
        maxLength: 100
        channelCustomProperties:
          - channel: apple
            properties:
              subtitle: Your House/Appartment No.
              options:
                keyboardType: numberPad
      - displayType: textInput
        name: street_address
        label: Street Name
        channelCustomProperties:
          - channel: apple
            properties:
              subtitle: Your Street Details
              options:
                keyboardType: default
        required: true
        maxLength: 200
      - displayType: numberInput
        name: zipcode
        label: Where do you live?
        placeholder: Enter your area zipcode
        channelCustomProperties:
          - channel: apple
            properties:
              subtitle: Zip-code
        required: true
    actions:
      - label: Submit
        type: submitForm
    channelCustomProperties:
      - channel: apple
        properties:
          showSummary: true
          receivedMessage:
            imageIdentifier: main
            subtitle: "Add your details carefully!"
            style: icon
            title: "Tap & Provide your Delivery details"
          images:
            - identifier: main
              imageUrl: "https://example.com/delivery-address.png"
            - identifier: saveAddress
              imageUrl: "https://example.com/successful-delivery.png"
          replyMessage:
            imageIdentifier: saveAddress
            style: icon
            title: Your address details are saved. Tap to review.
          splash:
            imageIdentifier: main

autenticazione

È possibile utilizzare il componente Collegamento account OAuth di Digital Assistant per i messaggi di autenticazione nei messaggi Apple per il business. Sono disponibili due approcci:

  • Nella proprietà Autorizza URL del componente Collegamento account OAuth, fornire i parametri di query responseType e scope.

    Quando l'autenticazione riesce, restituisce un codice di autorizzazione, che viene quindi utilizzato per recuperare un token di accesso.

  • Nella proprietà Autorizza URL del componente Collegamento account OAuth, fornire i parametri di query responseType, clientSecret e scope.

    Dopo l'autenticazione riuscita, restituisce un token di accesso.

iMessage App

Con Apple Messages for Business è possibile creare messaggi di tipo Applicazione iMessage, ovvero messaggi di dati interattivi personalizzati. Per far funzionare questi messaggi all'interno di un canale Apple Messages for Business in Digital Assistant, è necessario costruire il payload dei dati interattivo Apple nella competenza stessa utilizzando un componente personalizzato.

Il componente personalizzato deve inviare un messaggio CMM (Common Message Model) non elaborato contenente i seguenti attributi di payload:

  • type: interactive (obbligatorio)
  • interactiveData :
    • appIcon
    • appId
    • appName
    • URL (obbligatorio)
    • bid (obbligatorio)
    • receivedMessage
    • replyMessage
    • useLiveLayout

Per un'esercitazione sulla creazione di un'applicazione iMessage, consulta la sezione relativa all'integrazione dell'applicazione iMessage nella documentazione di Apple.

Per informazioni sull'uso del modello di messaggio comune di Digital Assistant, vedere la sezione Messaggistica di conversazione della documentazione dell'SDK del nodo bot.

Esempio: iMessage Payload applicazione

{
  "type": "interactive",
  "interactiveData": {
    "appId": 12345678,
    "appName": "Package Delivery",
    "URL": "?name=WWDC%20Goodies&deliveryDate=09-06-2017&destinationName=Moscone%20Convention%20Center&street=747%20Howard%20St&state=CA&city=San%20
Fransisco&country=USA&postalCode=94103&latitude=37%2E7831&longitude=%2D122%2E4041&extraCharge=15%2E00",
    "bid": "com.apple.messages.MSMessageExtensionBalloonPlugin:4R3L6Z3UP2:com.example.apple-samplecode.PackageDelivery4R3L6Z3UP2.MessagesExtension",
    "receivedMessage": {
      "title": "PackageDelivery",
      "subtitle": "Tap to Install the iMessage App from App Store"
    }
  }
}

ChannelCustomProperties per Apple Messages for Business

Nome Valori ammessi Si applica a... descrizione;
images Oggetto nidificato con le seguenti proprietà:
  • imageUrl
  • identifier, ovvero la stringa mediante la quale l'immagine viene utilizzata come riferimento dall'elemento imageIdentifier di altre proprietà, ad esempio receivedMessage.
  • description, che è una descrizione testuale facoltativa dell'immagine.
editForm elementi di risposta. Immagini definite per l'uso negli elementi dell'elenco e in altre posizioni del modulo.
receivedMessage Oggetto nidificato con le seguenti proprietà, tutte facoltative:
  • imageIdentifier
  • style
  • subtitle
  • title
 editForm elementi di risposta Messaggio visualizzato sopra un selettore elenco o un altro tipo di messaggio.
replyMessage Oggetto nidificato con le seguenti proprietà, tutte facoltative:
  • imageIdentifier
  • style
  • subtitle
  • title
 editForm elementi di risposta Messaggio visualizzato dopo che l'utente ha effettuato una selezione con un selettore specifico.
location Oggetto nidificato con le seguenti proprietà:
  • latitude
  • longitude
  • radius
  • title
 editForm elementi di risposta. Fornisce le coordinate per una determinata posizione.
showSummary
  • true
  • false
 editForm elementi di risposta. Se true, viene visualizzato un riepilogo delle opzioni selezionate dall'utente. L'impostazione predefinita è false.
splash Oggetto nidificato con le seguenti proprietà:
  • imageIdentifier
  • buttonTitle
  • header
  • splashText
 editForm elementi di risposta. Utilizzato per definire una pagina iniziale per il form.
timeZoneOffset A number editForm elementi di risposta. Differenza in minuti tra l'ora nel fuso orario della località e il GMT.
imageIdentifier Stringhe che corrispondono al valore identifier per qualsiasi immagine nell'array images. Oggetti nell'array options negli elementi di risposta editForm. Utilizzato per applicare un'immagine a una determinata opzione negli elementi di risposta di tipo editForm.
subtitle Una stringa qualsiasi. editForm elementi di risposta. Sottotitolo facoltativo per un selettore elenco.

Nota: anche le proprietà quali receivedMessage e replyMessage dispongono di un elemento subtitle facoltativo.

duration A number. editForm elementi di risposta con un displayType di timePicker Il numero di secondi della durata.
options Oggetto nidificato con proprietà quali keyboardType e dateFormat. Sono disponibili opzioni separate per i tipi di pagina datePicker e input. Vedere Documentazione sui messaggi di form di Apple. editForm elementi di risposta con un displayType di datePicker e textInput. Categoria di proprietà specifiche del canale Apple Messages for Business che possono essere utilizzate su singoli articoli.

Nota: questa categoria si distingue dall'elemento options dell'elemento items negli elementi di risposta editForm.

submitForm
  • true
  • false
oppure false		 Su singoli elementi nel tipo di elemento di risposta dataSet. Impostare su true se si desidera che il modulo venga inviato quando l'elemento è selezionato. L'impostazione predefinita è false.
pickerTitle Stringa Su singoli elementi nel tipo di elemento di risposta dataSet. Valore stringa che rappresenta il testo facoltativo visualizzato accanto al campo di testo del selettore. Questo valore assume per impostazione predefinita una stringa vuota. Se vuoto, il campo di testo del selettore si trova al centro della pagina
selectedItemIndex Numerico Su singoli elementi nel tipo di elemento di risposta dataSet. Facoltativamente, consente di impostare il numero di indice dell'articolo in un selettore che si desidera selezionare per impostazione predefinita. L'impostazione predefinita è 0.