Questa pagina è stata tradotta dall'API Cloud Translation.

Crea scorciatoie.xml

Dopo aver identificato la funzionalità in-app e il corrispondente intent integrato (BII) da implementare, dichiara gli intent integrati supportati dalla tua funzionalità definendo un elemento capability in un file di risorse shortcuts.xml. Dichiarazione di un intent integrato come capability registra il supporto per quell'intent semantico nella tua app, e consente il completamento dell'intent tramite query vocali utilizzando l'Assistente Google.

L'assistente usa l'elaborazione del linguaggio naturale per estrarre parametri da un utente query. Il riferimento per intent integrati elenca i campi in cui viene inserito ogni intent integrato in grado di estrarre da una query utente associata. Ad esempio, se un utente richiama la funzionalità [actions.intent.GET_FOOD_OBSERVATION][] nella tua app dicendo "Hey Google, chiedi ad ExampleApp cosa ho mangiato a pranzo venerdì scorso", assistente estrae i seguenti parametri dell'intent integrato dalla richiesta dell'utente:

foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
foodObservation.startTime = "06-09-2024T00:00:00"
foodObservation.endTime = "06-09-2024T23:59:59"

L'assistente passa i parametri dell'intent integrato al completamento intent definito nell' capability. In una funzionalità possono essere definiti uno o più elementi intent i diversi modi in cui un utente può richiamare un intent integrato. Ad esempio, è possibile definire un intent di completamento che richiede entrambi i parametri BII in dall'esempio riportato sopra. Potresti quindi definire un secondo intent che richiede un singolo intent integrato foodObservation.forMeal, che riporta tutti i pasti in un determinato giorno, ad esempio "Hey Google, chiedi ad ExampleApp cosa ho mangiato a pranzo".

Panoramica

Configuri le Azioni app utilizzando un file shortcuts.xml inserito nella tua app directory res/xml del progetto, quindi viene creato un riferimento a shortcuts.xml nel file manifest dell'app. Aggiungi un riferimento a shortcuts.xml nel file manifest dell'app procedendo nel seguente modo:

Nel file manifest dell'app (AndroidManifest.xml), trova un'attività la cui i filtri per intent sono impostati sull'azione android.intent.action.MAIN e Categoria android.intent.category.LAUNCHER.
Aggiungi un riferimento a shortcuts.xml in AndroidManifest.xml utilizzando un Tag <meta-data> in Activity che ha un intent filtri sia per MAIN che per LAUNCHER, come segue:
```
<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />
```

L'esempio riportato sopra dichiara una risorsa XML per il file xml/shortcuts.xml nell'APK. Per maggiori dettagli sulla configurazione delle scorciatoie, consulta Crea scorciatoie statiche nella documentazione per gli sviluppatori Android.

La raccolta Jetpack androidx.core:core:1.6.0 (o superiore) nel tuo progetto Android per evitare errori di compilazione quando definisci le funzionalità delle Azioni app in shortcuts.xml. Per maggiori dettagli, vedi Guida introduttiva ad Android Jetpack.

Scorciatoie statiche

Quando definisci capability, puoi dichiarare elementi shortcut statici in shortcuts.xml per estendere la funzionalità della funzionalità. Scorciatoie statiche vengono importati dall'assistente quando carichi una release su Google Play Console. Poiché le scorciatoie statiche possono essere create e aggiornate solo creando nuove release, sono più utili per mettere in evidenza attività e contenuti comuni nella tua app.

Puoi attivare la seguente funzionalità di Azioni app con scorciatoie statiche:

Scorciatoie delle funzionalità. Creare scorciatoie che avviano un'istanza di capability contenente valori di parametro intent predefiniti. Ad esempio: puoi dichiarare la scorciatoia dell'app "Avvia una corsa" che richiama il START_EXERCISE Funzionalità degli intent integrati nella tua app per l'attività fisica.

Queste scorciatoie contengono gli attributi intent, shortLabel e longLabel, pertanto possono essere suggerite e soddisfatte come chip nelle piattaforme proactive, come l'assistente o quando si preme a lungo l'icona di un'app sui avviatori Android. Una scorciatoia alle azioni può anche fungere da scorciatoia per un'entità, come descritto di seguito, associandolo a capability tramite un Tag <capability-binding>.
Scorciatoie per le entità. Le scorciatoie delle entità forniscono un elenco dei parametri supportati valori per il completamento di query vocali di un capability. Ad esempio, un'entità scorciatoia con un elenco di tipi di allenamento ("escursionismo", "corsa" ecc.) associati al exercise.name del parametro dell'intent integrato START_EXERCISE funzionalità. Se un'espressione dell'utente corrisponde a un'entità, l'ID shortcutId viene passato all'intent anziché al valore della query dell'utente non elaborato.

Entity scorciatoie non definiscono intent, shortLabel o longLabel che, in quanto tali, non sono suggeriti sulle piattaforme proattive. Per maggiori dettagli, consulta Inventario in linea per le azioni in-app.

Nota: le scorciatoie statiche dichiarate come scorciatoie entità vengono eliminate API LauncherApps, il che significa che sono disponibili per Avvio app di Android.

Schema delle funzionalità

La seguente tabella descrive lo schema di App Actions per gli elementi capability in shortcuts.xml. Quando includi un tag, tutti i suoi attributi sono obbligatori a meno che non sia contrassegnato come "facoltativo".

Tag Shortcuts.xml	All'interno di	Attributi
`<capability>`	`<shortcuts>`	`android:name` `app:queryPatterns` (applicabile solo per gli intent personalizzati)
`<intent>`	`<capability>`	`android:action` (facoltativo) `android:targetClass` (facoltativo) `android:targetPackage` (facoltativo) `android:data` (facoltativo)
`<url-template>`	`<intent>`	`android:value`
`<extra>`	`<intent>`	`android:key` `android:value` Applicabile solo per le chiamate di app in primo piano
`<parameter>`	`<intent>`	`android:name` `android:key` `android:mimeType` (applicabile solo per gli intent personalizzati) `android:required` (facoltativo) `app:shortcutMatchRequired` (facoltativo)
`<shortcut-fulfillment>`	`<capability>`	Applicabile solo per l'inventario in linea
`<parameter>`	`<shortcut-fulfillment>`	`android:name`
`<slice>`	`<capability>`	Applicabile solo alle sezioni Android

Descrizione schema di funzionalità

Questa sezione descrive gli elementi dello schema capability.

<capability>

Un capability che definisce l'intent dell'Azione app supportato dalla tua app. Ciascuna L'elemento <capability> nel file shortcuts.xml deve fornirne almeno uno <intent> per gestire il completamento dell'azione.

Attributi:

android:name: ID azione per intent integrato, ad esempio [actions.intent.GET_FOOD_OBSERVATION][]). Per un elenco delle consulta il riferimento agli intent integrati.
app:queryPatterns: una risorsa array di query delle query previste dalla dell'utente per questo intento. Questo attributo è applicabile solo a: intent personalizzati, poiché gli intent integrati includono già modelli modi comuni in cui gli utenti esprimono le attività che stanno cercando di svolgere o le informazioni che cercano.

di Gemini Advanced.

<intent>

Elemento intent di Android che definisce il modo in cui deve essere una query dell'utente mediante funzionalità in-app. Gli sviluppatori possono fornire più <intent> in un capability. L'assistente cerca di rispondere a una query dell'utente utilizzando primo <intent> in un capability per cui tutti i parametri obbligatori sono fornito.

Attributi:

android:action: il tipo Action di intent. Il valore predefinito è ACTION_VIEW.
android:targetClass: classe attività di destinazione, ad esempio: "com.example.exercise.ExerciseActivity"
android:targetPackage: pacchetto contenente la classe attività target, per esempio: "com.example.exercise
android:data: questo campo è stato sovrascritto da <url-template> se questo tag viene dichiarato in intent.

di Gemini Advanced.

<modello-url>

Modello per la creazione di un URI del link diretto per essere aperti sul dispositivo. Il modello può essere espanso con i parametri di intent integrati se sono disponibili tutti i parametri obbligatori per il modello. Per esempi di modello di URL HTTP, consulta la Articolo di Wikipedia sui modelli di URL. La è conforme alle specifiche del modello di URI RFC6570.

Di seguito sono riportati alcuni esempi di valori dei modelli di URL:

Modello	Valori	Valore espanso
`https://example.com/test{?foo,bar}`	`"foo": "123"` `"bar": "456"`	`https://example.com/test?foo=123&bar=456`
`https://example.com/test?utm_campaign=appactions{&foo,bar}`	`"foo": "123"` `"bar": "456"`	`https://example.com/test?utm_campaign=appactions&foo=123&bar=456`
`https://example.com/test?utm_campaign=appactions{#foo}`	`"foo": "123"`	`https://example.com/test?utm_campaign=appactions#foo=123`
`myapp://example/{foo}`	`"foo": "123"`	`myapp://example/123`

Per ulteriori informazioni sulla configurazione dei modelli di URL, consulta Modelli di URL in fase di completamento.

<extra>

Definisce i dati aggiuntivi per un valore intent. Per le Azioni app, questo campo viene utilizzato solo per abilita [invocazione app in primo piano][] per capability.

<parametro>

Mappa un parametro dell'intent integrato ai valori dei parametri di intent. Per ulteriori informazioni, vedi Dati dei parametri e corrispondenza.

Attributi:

android:name: nome del parametro dell'intent integrato da associare a questo intent . Il nome deve essere un campo a livello di foglia del parametro dell'intent integrato (ad ad esempio foodObservation.aboutFood.name).
android:key: chiave definita dallo sviluppatore di un valore parametro dell'intent integrato. Ad esempio: potresti definire contact_name per l'intent integrato message.recipient.name .
android:mimeType: il tipo MIME del parametro, ad esempio text/*. Questo è obbligatorio solo per i parametri degli intent personalizzati.
android:required: indica se la query dell'utente deve includere questo parametro affinché questo intento venga utilizzato per l'evasione. Se il parametro non è disponibile, l'assistente tenta di soddisfare la query dell'utente utilizzando il prossimo intent definito per capability.

<scorciatoia-fulfillment>

Specifica che un intent definito in una scorciatoia per l'inventario in linea per un il parametro specificato per il completamento. Per maggiori dettagli, consulta Completamento con intent delle scorciatoie.

<parametro> (per `<shortcut-fulfillment>`)

Attributo facoltativo che mappa un singolo parametro dell'intent integrato all'inventario in linea completamento della scorciatoia. Per maggiori dettagli, consulta Completamento con intent delle scorciatoie.

Attributo:

android:name: nome del parametro dell'intent integrato da associare all'inventario in linea completamento della scorciatoia. Il nome deve essere un campo a livello foglia dell'intent integrato (ad esempio menuItem.name).

<sezione>

Consente all'assistente di incorporare il risultato di una query corrispondente a questo capability come sezione Android. Per maggiori dettagli, vedi Integrare le Azioni app con Android Slices.

Schema della scorciatoia

La seguente tabella descrive gli attributi degli elementi shortcut utilizzati per: attivare la funzionalità Azioni app. Quando includi un tag, tutti i suoi attributi sono obbligatori, a meno che non siano indicati come "facoltativo".

Tag Shortcuts.xml	All'interno di	Attributi
`<shortcut>`	`<shortcuts>`	`android:shortcutId` `android:shortcutShortLabel` `android:shortcutLongLabel` (facoltativo) `android:icon` (facoltativo)
`<intent>`	`<shortcut>`	`android:action` `android:targetClass` (facoltativo) `android:targetPackage` (facoltativo) `android:data` (facoltativo)
`<capability-binding>`	`<shortcut>`	`android:key`
`<parameter-binding>`	`<capability-binding>`	`android:key` (facoltativo) `android:value`
`<extra>`	`<shortcut>`	`android:name` (facoltativo) `android:value` Applicabile solo per la corrispondenza dei parametri enum.

Descrizione schema della scorciatoia

Questa sezione descrive gli elementi dello schema shortcut.

<scorciatoia>

Un <shortcut> Android definito in shortcuts.xml con determinati attributi pertinenti per le azioni di app. Valori stringa per shortcutShortLabel e shortcutLongLabel di campi viene fatto riferimento tramite risorse stringa.

Attributi:

android:shortcutId: identificatore per questa scorciatoia.
android:shortcutShortLabel: risorsa stringa che rappresenta una breve scorciatoia a frase. Ad esempio, "@string/callDavidShort" che rappresenta il valore "Chiamata David".
android:shortcutLongLabel: risorsa stringa che rappresenta una scorciatoia lunga a frase. Ad esempio, "@string/callDavidLong" che rappresenta il valore "Rendi a Davide".

<intent>

Intent Android associato a questa scorciatoia. Questo intent viene eseguito quando l'utente avvia questa scorciatoia tramite comandi vocali o tocco.

shortcut attributi per intenzione sono identici a capability intent attributi.

<capability-binding>

Associa un shortcut ad Azioni app capability. Aggiunta di questo elemento a shortcut consente il completamento vocale utilizzando Assistant.

Attributi:

android:key: l'attributo android:name del capability a cui è associato questo shortcut. Ad esempio: actions.intent.START_EXERCISE.

<parameter-binding>

Attributo facoltativo che associa shortcut a un singolo parametro di un'app Azioni capability. Se viene definito un parameter-binding per un shortcut, il valore può essere utilizzata per fornire un'entità di inventario in linea a un parametro dell'intent integrato. Per ulteriori dettagli, consulta Inventario in linea per App Actions.

Attributi:

android:key: il nome del parametro dell'intent integrato capability da associare questa scorciatoia. Ad esempio, exercise.name.
android:value: il valore di entity. Può essere un singolo entity o un dell'elenco delle risorse.

<extra>

Il gruppo di dati extra per la scorciatoia. sameAs è l'unico dato pertinente agli elementi shortcut delle Azioni app. L'URL sameAs si riferisce a una pagina web di riferimento che identifica in modo inequivocabile l'entità. Utilizzato per specificare valore enum se e solo se il tipo di parametro di intent è un sottotipo di schema.org/Enumeration. È obbligatorio per i campi dei parametri i cui tipi sono sottotipi di schema.org/Enumeration (ad esempio: MealTypeBreakfast).

Attributi:

android:key: il valore supportato per Azioni app è sameAs
android:value: il valore dell'URL sameAs

Per maggiori dettagli, consulta Corrispondenza dei valori dei parametri enumerati.

Opzioni di completamento dell'intent

Devi definire gli elementi intent in un <capability> per dichiarare in che modo l'assistente Risponde o completa i comandi vocali dell'utente corrispondenti a quella funzionalità. Là sono disponibili diversi modi per configurare il modo in cui un intent avvia una destinazione di evasione nell'app, a seconda di come è strutturata la navigazione.

Sono disponibili le seguenti opzioni di evasione degli ordini:

Intent espliciti: avvia un componente dell'app specifico definendo gli attributi targetClass e targetPackage per intent. Questo è il metodo di completamento delle Azioni app consigliato.
Link diretti. Avvia le destinazioni delle app utilizzando i link diretti di Android definendo un tag <url-template> nell'elemento intent. Questo è utile se la navigazione nell'app si basa già su link diretti.
Dati relativi all'intent: puoi fornire un URI di fulfillment nel intent android:data. Questo campo è sovrascritto dai dati di <url-template> se questo tag è definito anche in intent.

di Gemini Advanced.

Dati dei parametri e corrispondenza

Per impostazione predefinita, l'assistente invia i parametri degli intent integrati estratti dalla query dell'utente al tuo come dati di extra di Android intent definiti in capability.

In alternativa, puoi dichiarare un tag <url-template> nella capability che contiene segnaposto per i parametri dinamici. Questo modello viene mappato a una delle tue attività Android utilizzando un URL del link alle app, uno schema personalizzato o un URL basato sull'intent.

Utilizzo degli extra per intent

L'esempio seguente mostra un intent esplicito definito per un capability distribuzione:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Dato l'esempio sopra, per una query utente come "Hey Google, ordina un latte macchiato da ExampleApp", l'app riceve un intent che richiama il componente: targetPackage targetClass. Il componente riceve un extra con key = "exercise", value = "Running".

Utilizzo di un modello di URL per i link diretti Android

Se la tua app è già in grado di gestire gli URL collegati all'app con parametri dinamici, puoi definire un <url-template> in intent per generare Android link diretti per il fulfillment. Nell'esempio seguente viene definito un <url-template>:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Dato l'esempio sopra, per una query utente del tipo "Hey Google, ordina un latte macchiato". da ExampleApp", l'app riceve l'URL generato: "myapp://start?exercise=Running".

Per mappare il parametro dell'intent integrato a una posizione nell'URL, utilizza la classe Attributo android:name del tag <parameter>. Questo attributo corrisponde al valore android:key nel modello di URL che vuoi sostituire con informazioni fornite dall'utente. Il valore android:key deve essere presente in <url-template> e tra parentesi graffe ({}).

Crea corrispondenze con i valori dei parametri enumerati

Alcuni parametri dell'intent integrato forniscono valori enumerati all'intento di completamento, Ad esempio, i valori di testo supportati dell'intent integrato RECORD_FOOD_OBSERVATION. Per questi parametri, l'assistente abbina la query dell'utente ("Colazione") a un entità il cui valore sameAs corrisponde all'URL dello schema enum (https://schema.googleapis.com/MealTypeBreakfast). Per associare l'enum per un elemento entity supportato, dichiari un'associazione sameAs in il tuo shortcut. L'esempio seguente mostra un'associazione sameAs per un scorciatoia entità in linea:

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

Nell'esempio precedente, se la funzionalità RECORD_FOOD_OBSERVATION attiva un corrispondenza per "colazione" pasto, il seguente Extra viene inviato con evasione degli ordini intent:

key = "for_meal"
value = "meal_breakfast"

Funzionalità

Le seguenti funzionalità di Azioni app sono disponibili in shortcuts.xml.

Inventario incorporato per Azioni app

Per alcuni parametri degli intent integrati, puoi usare le scorciatoie per guidare le entità a un insieme di entità supportate specificate in shortcuts.xml, noto come inventario in linea. Per maggiori dettagli, vedi Inventario incorporato.

Segmenti di pubblico personalizzati per intenzione

Gli intent personalizzati per intent possono essere dichiarati in shortcuts.xml per consentire l'attivazione vocale delle funzionalità in dell'app che non corrispondono agli intent integrati disponibili. Sebbene simili per funzionalità a una definizione BII, gli intent personalizzati richiedono due attributi aggiuntivi in shortcuts.xml:

app:queryPatterns: risorsa array che dichiara la modelli di query diversi per un intent personalizzato.
android:mimeType: tipo di parametro di un intent personalizzato. Questo campo è non richiesto per gli intent integrati, in cui il tipo di parametro è noto. Per i parametri di intent personalizzati, è necessario dichiarare un tipo di semantica supportato.

Per maggiori dettagli, consulta la sezione Intenti personalizzati.

Crea scorciatoie.xml

Panoramica

Scorciatoie statiche

Schema delle funzionalità

Descrizione schema di funzionalità

<capability>

<intent>

<modello-url>

<extra>

<parametro>

<scorciatoia-fulfillment>

<parametro> (per <shortcut-fulfillment>)

<sezione>

Schema della scorciatoia

Descrizione schema della scorciatoia

<scorciatoia>

<intent>

<capability-binding>

<parameter-binding>

<extra>

Opzioni di completamento dell'intent

Dati dei parametri e corrispondenza

Utilizzo degli extra per intent

Utilizzo di un modello di URL per i link diretti Android

Crea corrispondenze con i valori dei parametri enumerati

Funzionalità

Inventario incorporato per Azioni app

Segmenti di pubblico personalizzati per intenzione

<parametro> (per `<shortcut-fulfillment>`)