Chiamata in primo piano dell'app

Azioni app consente agli utenti di parlare con l'Assistente Google e passare direttamente a contenuti destinazioni delle app quando dicono ad esempio "Hey Google, ordinami un passaggio Esempio di app." Con le chiamate alle app in primo piano, puoi migliorare ulteriormente le quando un utente ha già aperto la tua app.

La chiamata ad app in primo piano consente di trovare corrispondenze tra intent integrati senza richiedere la menzione del nome dell'app mentre è in corso un'attività specifica in primo piano del dispositivo.

Ad esempio, un utente ha la tua app di ridesharing in primo piano e dice o digita: "Ordinami una corsa per Mountain View" per l'Assistente Google. La tua app utilizza questo per impostare il campo di destinazione su Mountain View. Quindi, quando l'utente dice o Tipi, "Ordinami una corsa da SFO", la tua app può impostare il ritiro posizione mantenendo lo stato dell'app.

Limitazioni

La chiamata all'app in primo piano è disponibile solo per i seguenti intent integrati:

• actions.intent.CREATE_MONEY_TRANSFER
• actions.intent.CREATE_TAXI_RESERVATION
• actions.intent.OPEN_APP_FEATURE
• actions.intent.ORDER_MENU_ITEM
• actions.intent.PAUSE_EXERCISE
• actions.intent.RECORD_EXERCISE
• actions.intent.RECORD_FOOD_OBSERVATION
• actions.intent.RESUME_EXERCISE
• actions.intent.START_EXERCISE
• actions.intent.STOP_EXERCISE

Per ricevere assistenza relativa alle impostazioni internazionali e query di esempio relative alla chiamata di app in primo piano per un intent integrato specifico, consulta il riferimento all'intent integrato.

Nota: la chiamata all'app in primo piano non può essere testata utilizzando il pulsante Esegui nella Strumento di test delle Azioni app. Per provare la chiamata all'app in primo piano prima dell'app invio, attiva l'Azione app sul dispositivo di test usando l'Assistente Google dopo aver creato un'anteprima per la tua app.

Supporta la chiamata di app in primo piano

L'aggiunta del supporto per le chiamate alle app in primo piano comporta l'aggiunta del completamento comportamento in base all'attività in primo piano desiderata. Quando quell'attività si trova nella in primo piano e viene richiamata l'Azione app, l'assistente trasmette l'intent del link diretto con un flag aggiuntivo all'attività in modo che l'app possa aggiornare il proprio stato.

Nota: quando utilizzi i frammenti come destinazioni nella tua app, comunica l'intento informazioni al frammento pertinente.

Per implementare la chiamata ad app in primo piano per un intent integrato, segui questi passaggi:

1. Nel file shortcuts.xml, aggiungi un tag <intent> all'intent integrato <capability> vuoi supportare la chiamata di app in primo piano.
2. All'interno del tag <intent>, aggiungi un tag <extra>.
3. Nel tag <extra>, imposta android:key su "requiredForegroundActivity", e imposta android:value sull'attività che vuoi in primo piano. Specifica l'attività senza corsi abbreviazioni, utilizzando il nome del pacchetto dell'app seguito da una barra (/), seguito dal nome dell'attività: APP_PACKAGE_NAME/ACTIVITY_NAME
4. Nell'attività in primo piano che hai specificato per "requiredForegroundActivity", implementare il metodo onNewIntent() per gestire un intent relativo a un link diretto con il flag SINGLE_TOP impostato. L'assistente trasmette l'intent del link diretto questo flag come completamento quando l'attività specificata è in primo piano.
5. Tratta le chiamate al numero onNewIntent() come aggiornamenti alle tue attività in primo piano e gestire lo stato dell'attività utilizzando i parametri estratti dal link diretto.

di Gemini Advanced.

Nota: gli intent si risolvono dall'alto verso il basso, quindi inserisci gli intent con un attività in primo piano rispetto ad altri intent in un <capability> per dare loro la priorità.

Se la tua app usa un'attività router per consentire a tutti i link diretti esterni di attivare un'attività l'attività di un singolo router, vedi Gestire le attività del router.

Esempio

Il seguente snippet di un file shortcuts.xml di esempio mostra come aggiungere il parametro Attributo requiredForegroundActivity:

  <capability name="actions.intent.CREATE_TAXI_RESERVATION">
      <!-- Trigger with foreground app invocation if MainActivity is in the foreground. -->
      <intent
          android:targetClass="com.example.app.MainActivity"
          android:targetPackage="com.example.app">
          <parameter
              android:name="taxiReservation.dropoffLocation.name"
              android:key="dropoff" />
          <extra
              android:key="requiredForegroundActivity"
              android:value="com.example.app/com.example.app.MainActivity" />
      </intent>
      <!-- This won't trigger if MainActivity is in the foreground. -->
      <intent
          android:targetClass="com.example.app.MainActivity"
          android:targetPackage="com.example.app">
          <parameter
              android:name="taxiReservation.dropoffLocation.name"
              android:key="dropoff" />
      </intent>
  </capability>

Autorizzazioni utente

Affinché la chiamata all'app in primo piano funzioni, gli utenti devono avere l'impostazione del dispositivo Utilizza testo sullo schermo attivata. La posizione e il nome esatto di questa impostazione può variare in base all'OEM o al produttore del dispositivo. Ad esempio, l'impostazione del dispositivo potrebbe chiamarsi Usa il contesto dello schermo dispositivo.

Per accedere a questa impostazione Android su uno smartphone Pixel, vai su Impostazioni > App e notifiche > App predefinite > App di assistenza. Quindi, nella sezione Assistenza e schermata di immissione, attiva l'opzione Utilizza testo sullo schermo.

Testa la chiamata

Per provare la chiamata dell'app in primo piano, svolgi i seguenti passaggi:

1. Segui le istruzioni nella sezione Autorizzazioni utente per attivare la Impostazione del dispositivo Utilizza testo sullo schermo.
2. Apri l'app per l'attività che hai elencato come attività in primo piano richiesta.
3. Premi & tieni premuto il pulsante Home per aprire l'assistente come overlay sul pannello dell'app. Fornisci una query corrispondente all'intent integrato che hai implementato senza menzionare il nome dell'app. Se l'operazione ha esito positivo, l'app viene aggiornata automaticamente in base alla query, mantenendo lo stato e senza riavviarsi l'attività.

Gestire le attività del router

Alcune app gestiscono tutti i link diretti esterni utilizzando un unico router di gatekeeping attività. L'attività del router avvia quindi la logica di business appropriata dell'attività (dopo eventuali controlli e convalide) e restituisce la logica di business l'attività in primo piano.

L'attivazione di un link diretto può causare l'aggiunta dell'attività del router nella parte superiore della allo stack delle attività, sopra l'attività in primo piano. Per le app che utilizzano un router devi assicurarti che l'attività del router fornisca l'intent inviato dall'Assistente Google all'istanza attuale dell'attività in primo piano. Come raggiungi questo requisito cambia a seconda di dove inizia l'attività del router.

Se il router viene avviato nello stesso stack di attività della logica di business, inoltrare l'intent utilizzando l'OR a livello di bit di SINGLE_TOP, CLEAR_TOP e NEW_TASK:

Kotlin

Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_NEW_TASK

Java

Intent.FLAG_ACTIVITY_SINGLE_TOP | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK

Se il router viene avviato in uno stack di attività separato dalla logica di business attività, inoltra l'intent con il flag SINGLE_TOP all'attività dell'attività logica.