Chiamata in primo piano dell'app

Azioni app consente agli utenti di parlare con l'Assistente Google e passare direttamente a destinazioni specifiche dell'app quando dicono ad esempio "Hey Google, ordinami una corsa nell'app di esempio". Con la chiamata di app in primo piano, puoi migliorare ulteriormente l'esperienza quando un utente ha già aperto la tua app.

La chiamata dell'app in primo piano consente di associare gli intent integrati (BII) senza che sia necessario menzionare il nome dell'app quando un'attività specifica è in primo piano sul dispositivo.

Ad esempio, un utente ha la tua app di ridesharing in primo piano e dice o digita "Ordinami un passaggio per Mountain View" all'Assistente Google. L'app utilizza questo input per impostare il campo di destinazione su Mountain View. Quando l'utente dice o digita "Ordinami una corsa da MXP", la tua app può impostare la località di prelievo mantenendo lo stato dell'app.

Limitazioni

La chiamata di app in primo piano è disponibile solo per i seguenti BII:

Per ottenere supporto delle impostazioni internazionali e query di esempio relative alla chiamata di app in primo piano per uno specifico BII, consulta il riferimento per intent integrato.

Supporto delle chiamate di app in primo piano

L'aggiunta del supporto per le chiamate di app in primo piano comporta l'aggiunta del comportamento di fulfillment in base a un'attività in primo piano desiderata. Quando l'attività è in primo piano e viene richiamata l'Azione app, l'assistente trasmette l'intent del link diretto con un ulteriore flag all'attività in modo che l'app possa aggiornarne lo stato.

Per implementare la chiamata di un'app in primo piano per un BII:

  1. Nel file shortcuts.xml, aggiungi un tag <intent> a BII<capability> che vuoi supportare le chiamate all'app in primo piano.
  2. Nel tag <intent>, aggiungi un tag <extra>.
  3. Nel tag <extra>, imposta android:key su "requiredForegroundActivity" e imposta android:value sull'attività che deve essere in primo piano. Specifica l'attività senza abbreviazioni della classe, utilizzando il nome del pacchetto dell'app, seguito da una barra (/), seguita dal nome dell'attività: APP_PACKAGE_NAME/ACTIVITY_NAME
  4. Nell'attività in primo piano specificata per "requiredForegroundActivity", implementa il metodo onNewIntent() per gestire un intent di link diretto con il flag SINGLE_TOP impostato. L'assistente trasmette l'intent del link diretto con questo flag come fulfillment quando l'attività specificata è in primo piano.
  5. Tratta le chiamate a onNewIntent() come aggiornamenti dell'attività in primo piano e gestisci lo stato di questa attività utilizzando parametri estratti dal link diretto.

Se la tua app utilizza un'attività del router per consentire a tutti i link diretti esterni di attivare una singola attività del router di gatekeeping, consulta Gestire le attività del router.

Esempio

Il seguente snippet da un file shortcuts.xml di esempio mostra come aggiungere l'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

Nelle impostazioni del dispositivo, gli utenti devono abilitare l&#39;opzione &quot;Utilizza il testo dello schermo&quot;
            affinché le chiamate dell&#39;app in primo piano funzionino.

Affinché le chiamate di app in primo piano funzionino per un utente, l'utente deve aver attivato l'impostazione del dispositivo Utilizza testo dallo schermo. La posizione e il nome esatto di questa impostazione possono variare in base all'OEM o al produttore del dispositivo. Ad esempio, l'impostazione del dispositivo potrebbe essere chiamata Usa il contesto dello schermo sul dispositivo di un utente.

Per accedere a questa impostazione di Android su uno smartphone Pixel, vai innanzitutto a Impostazioni > App e notifiche > App predefinite > App di assistenza. Quindi, nella schermata Assistente e input vocale, attiva l'opzione Usa testo dallo schermo.

Testa la chiamata

Per provare a richiamare l'app in primo piano, procedi nel seguente modo:

  1. Segui le istruzioni nella sezione Autorizzazioni utente per attivare l'impostazione del dispositivo Utilizza testo sullo schermo.
  2. Apri l'app in corrispondenza dell'attività indicata come attività in primo piano richiesta.
  3. Tieni premuto il pulsante Home per aprire l'assistente come overlay sull'app corrente. Fornisci una query che corrisponda allo standard BII implementato senza menzionare il nome dell'app stesso. In caso di esito positivo, l'app si aggiorna in base alla query, mantenendo lo stato e senza riavviare l'attività.

Gestire le attività del router

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

L'attivazione di un link diretto può causare l'aggiunta dell'attività del router all'inizio dello stack di attività, sopra l'attività in primo piano. Per le app che utilizzano un'attività del router, devi assicurarti che l'attività del router fornisca l'intent inviato dall'Assistente Google all'istanza dell'attività in primo piano corrente. Il modo in cui soddisfi questo requisito cambia a seconda di dove inizia l'attività del router.

Se il router si avvia nello stesso stack di attività dell'attività della logica di business, inoltra l'intent utilizzando l'operatore 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 si avvia in uno stack di attività separato dall'attività della logica di business, inoltra invece l'intent con il flag SINGLE_TOP all'attività della logica di business.