Ativar e personalizar a transferência entre dispositivos

O recurso Continuar no Dispositivo apresenta novos métodos e classes para você indicar suporte ao recurso e fornecer os dados necessários que são transmitidos. Isso permite retomar corretamente a experiência do usuário no dispositivo receptor.

Ativar suporte

O suporte para o recurso Continuar em (desativado por padrão) precisa ser implementado por atividade. Para ativar o recurso, chame setHandoffEnabled para indicar que a atividade atual está pronta para transferência. Depois que setHandoffEnabled(true, null) é chamado, a transferência pode acontecer a qualquer momento para a atividade. Portanto, só chame-o quando a atividade estiver pronta para ser transferida.

Verifique se a atividade ativou o recurso Continuar em outro dispositivo com isHandoffEnabled. Se uma atividade tiver a transferência ativada, ela também precisará implementar onHandoffActivityDataRequested para garantir que retorne um HandoffActivityData não nulo, já que nenhum comportamento padrão é implementado.

class MyHandoffActivity : Activity() {

    ...

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Do stuff
    ...
    // Enable handoff
    setHandoffEnabled(true, null)
  }

  // Override and implement onHandoffActivityDataRequested
  override fun onHandoffActivityDataRequested(handoffRequestInfo: HandoffActivityDataRequestInfo) : HandoffActivityData {
    // Create and return handoff data
  }
}

Configure o objeto HandoffActivityData com todos os extras relevantes e um URI substituto para informar ao Continue On como realizar a transferência para o dispositivo receptor.

Há duas situações em que esses dados são necessários para o sistema:

  • A atividade está indo para o segundo plano, e os dados relevantes precisam ser salvos.
  • A atividade está em primeiro plano, e a transferência foi solicitada. É possível verificar o status de uma solicitação de transferência.

Verificar status

A classe HandoffActivityDataRequestInfo fornece informações sobre a solicitação atual para transferir uma atividade. Use isActiveRequest para determinar se a solicitação está ativa. Se o método retornar

  • true, a atividade atual está em primeiro plano e o usuário pediu para continuar em outro dispositivo. No entanto, se
  • false, a atividade foi interrompida e está em segundo plano, mas o usuário pode solicitar uma transferência no futuro.

No dispositivo de envio, se você quiser mostrar uma interface para indicar ao usuário que uma transferência ocorreu ou está em andamento, verifique se há uma solicitação ativa em isActiveRequest. No entanto, não execute esse código de forma síncrona como parte de onHandoffActivityDataRequested. Em vez disso, coloque na fila qualquer código para ser executado de forma assíncrona, para não bloquear ou atrasar a transferência.

// Override and implement onHandoffActivityDataRequested
override fun onHandoffActivityDataRequested(handoffRequestInfo: HandoffActivityDataRequestInfo) : HandoffActivityData {

  // Check whether the handoff request is active
  if (handoffRequestInfo.isActiveRequest()) {
    // Asynchronously show UI to let users know a handoff is in progress
  }

  // Create and return handoff data
}

Criar dados de transferência

Para garantir que todos os dados relevantes e necessários sejam transmitidos durante a transferência com o recurso Continuar em, inclua os dados no objeto HandoffActivityData.

A classe HandoffActivityData representa os dados de transferência associados a uma atividade. HandoffActivityData informa ao recurso Continuar Em como processar e recriar uma atividade no dispositivo receptor. Os dados de transferência incluem:

  • Nome do componente (obrigatório): o ComponentName de uma atividade correspondente a ser iniciada no dispositivo receptor para retomar a jornada do usuário após a transferência. Na maioria dos casos e para a replicação exata da atividade, esse será o nome do componente da mesma atividade que cria o HandoffActivityData.
  • Extras (opcional): é possível especificar extras que serão incluídos no início Intent da atividade. É um PersistableBundle que pode ser usado para fornecer mais informações ao componente. Os extras precisam ter menos de 50 KB.

Para criar objetos HandoffActivityData, use a classe builder, HandoffActivityData.Builder. Crie um novo builder transmitindo o ComponentName da atividade que vai receber a transferência (por exemplo, this.getComponentName para o Activity atual ou um ComponentName(this, TargetActivity::class.java) explícito). Em seguida, use o método setExtras para especificar extras, se quiser. Por fim, chame build para criar o objeto HandoffActivityData.

// Override and implement onHandoffActivityDataRequested
override fun onHandoffActivityDataRequested(handoffRequestInfo: HandoffActivityDataRequestInfo) : HandoffActivityData {

  // Check whether the handoff request is active
  if (handoffRequestInfo.isActiveRequest()) {
    // Asynchronously show UI to let users know a handoff is in progress
  }

  val extras: PersistableBundle = PersistableBundle()
  // Put relevant and necessary values into extras (e.g. scroll position)
  extras.putString("data_id", getDataId())
  extras.putInt("scroll_position", getScrollPosition())

  // Create and return handoff data
  return HandoffActivityData.Builder(getComponentName()) // Designate handoff to the same activity
    .setExtras(extras)
    .build()
}

Definir opção de substituto da Web

Caso a atividade especificada não possa ser iniciada no dispositivo receptor, use setFallbackUri para definir um URL alternativo que será aberto no dispositivo no navegador padrão do usuário.

Para permitir que a sugestão "Continuar em" apareça nos dispositivos de recebimento em que o app não está instalado, transmita uma instância de HandoffActivityParams com setAllowHandoffWithoutPackageInstalled definido como true ao chamar setHandoffEnabled:

setHandoffEnabled(
  true,
  HandoffActivityParams.Builder()
    .setAllowHandoffWithoutPackageInstalled(true)
    .build()
)

Em seguida, inclua o URL alternativo no seu HandoffActivityData:

val fallbackWebLink: Uri = Uri.parse("https://myapp.com/fallback?query=" + paramVal)

val handoffData: HandoffActivityData = HandoffActivityData.Builder(getComponentName())
  .setExtras(extras)
  .setFallbackUri(fallbackWebLink)
  .build()

Implementar o Direct to Web

Como alternativa, para implementar a transferência direta para a Web, transmita HandoffActivityParams com setAllowHandoffWithoutPackageInstalled(true) para setHandoffEnabled e use o método HandoffActivityData.createWebHandoff para gerar o HandoffActivityData:

val webHandoffLink: Uri = Uri.parse("https://myapp.com/handoff?query=" + paramVal)

val handoffData: HandoffActivityData = HandoffActivityData.createWebHandoff(webHandoffLink)

Receber e processar a intent de transferência

No dispositivo receptor, o app precisa processar a transferência e recriar a experiência do usuário do dispositivo de envio. Especificamente, na atividade especificada no HandoffActivityData retornado por onHandoffActivityDataRequested, é necessário processar a intent e recuperar os extras que têm informações sobre como recriar a atividade adequadamente.

Se você estiver especificando a transferência para a mesma atividade, poderá receber a intent no método onCreate da atividade para que os dados possam ser recuperados e pré-preenchidos adequadamente para o usuário.

class MyHandoffActivity : Activity() {

    ...

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // Do stuff
    ...

    // Get the launch intent and retrieve extras
    val intent: Intent = getIntent()
    if (intent != null && intent.hasExtra("data_id")) {
      val dataID: String = intent.getStringExtra("data_id")
      // Retrieve the data that corresponds to the data ID
      ...
      // Populate activity UI with relevant data
      ...

      if (intent.hasExtra("scroll_position")) {
        val scrollPosition: Int = intent.getIntExtra("scroll_position", 0)
        // Move the page to the scroll position
        ...
      }
    }
  }
}