Sessions API

Device DiscoverySecure Connection API 為基礎, Sessions API 提供強大的抽象化機制,可打造順暢的跨裝置體驗 這點十分重要工作階段代表可滿足下列條件的應用程式使用者體驗 。

Sessions API 也是以個人與共同為核心打造而成 工作階段轉移和工作階段共用用途代表的體驗 。下圖說明高階的工作階段:

圖 1. 工作階段圖表。

建立及轉移工作階段

Sessions API 可區分來源裝置和接收裝置。來源裝置會建立工作階段,並搜尋 可處理工作階段的裝置。來源裝置的使用者 會從系統對話方塊提供的清單中選取裝置。使用者 選取接收裝置,系統會轉移及移除來源工作階段 來自原始裝置

如要轉移工作階段,請先使用下列方法建立工作階段: 參數:

  • 應用程式工作階段標記,讓您用來區分 在應用程式中的多個工作階段之間來回切換

然後使用下列參數啟動轉移程序:

  • DeviceFilter,用於篩選可處理工作階段的裝置
  • 實作 OriginatingSessionStateCallback 的回呼物件

在原始裝置上,使用下方範例建立工作階段:

KotlinJava
private val HELLO_WORLD_TRANSFER_ACTION = "hello_world_transfer"
private lateinit var originatingSession: OriginatingSession
private lateinit var sessions: Sessions

override fun onCreate(savedInstanceState: Bundle?) {
 
super.onCreate(savedInstanceState)
  sessions
= Sessions.create(context = this)
}

suspend fun transferSession() {
 
val sessionId =
    sessions
.createSession(
     
ApplicationSessionTag("hello_world_transfer"),
   
)
  originatingSession
=
    sessions
.transferSession(
      sessionId
,
     
StartComponentRequest.Builder()
       
.setAction(HELLO_WORLD_TRANSFER_ACTION)
       
.setReason("Transfer reason here")
       
.build(),
      emptyList
(),
     
HelloWorldTransferSessionStateCallback()
   
)
}
private static final String HELLO_WORLD_TRANSFER_ACTION = "hello_world_transfer";
private OriginatingSession originatingSession;
private Sessions sessions;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
 
super.onCreate(savedInstanceState);
  sessions
= Sessions.create(/* context= */ this);
}

public void transferSession() {
 
SessionId sessionId = sessions.createSession(new ApplicationSessionTag("hello_world_transfer"));
 
ListenableFuture<OriginatingSession> originatingSessionFuture =
      sessions
.transferSessionFuture(
          sessionId
,
         
new StartComponentRequest.Builder()
             
.setAction(HELLO_WORLD_TRANSFER_ACTION)
             
.setReason("Transfer reason here")
             
.build(),
         
Collections.emptyList(),
         
new HelloWorldTransferSessionStateCallback());
 
Futures.addCallback(
      originatingSessionFuture
,
     
new FutureCallback<>() {
       
@Override
       
public void onSuccess(OriginatingSession result) {
         
// Do nothing, handled in HelloWorldTransferSessionStateCallback
          originatingSession
= result;
       
}

       
@Override
       
public void onFailure(Throwable t) {
         
Log.d(TAG, "onFailure called for transferSessionFuture", t);
       
}
     
},
      mainExecutor
);
}

接著,請在原始裝置上定義工作階段回呼:

KotlinJava
private inner class HelloWorldTransferSessionStateCallback : OriginatingSessionStateCallback {
 
override fun onConnected(sessionId: SessionId) {
   
val startupRemoteConnection = originatingSession.getStartupRemoteConnection()
    lifecycleScope
.launchWhenResumed {
      startupRemoteConnection
.send("hello, world".toByteArray(UTF_8))
      startupRemoteConnection
.registerReceiver(
       
object : SessionConnectionReceiver {
         
override fun onMessageReceived(participant: SessionParticipant, payload: ByteArray) {
           
val ok = payload.contentEquals("ok".toByteArray(UTF_8))
           
Log.d(TAG, "Session transfer initialized. ok=$ok")
         
}
       
}
     
)
   
}
 
}

 
override fun onSessionTransferred(sessionId: SessionId) {
   
Log.d(TAG, "Transfer done.")
 
}

 
override fun onTransferFailure(sessionId: SessionId, exception: SessionException) {
   
// Handle error
 
}
}
private class HelloWorldTransferSessionStateCallback implements OriginatingSessionStateCallback {
 
@Override
 
public void onConnected(SessionId sessionId) {
   
SessionRemoteConnection startupRemoteConnection =
        originatingSession
.getStartupRemoteConnection();
   
Futures.addCallback(
        startupRemoteConnection
.sendFuture("hello, world".getBytes()),
       
new FutureCallback<>() {
         
@Override
         
public void onSuccess(Void result) {
           
Log.d(TAG, "Successfully sent initialization message");
         
}

         
@Override
         
public void onFailure(Throwable t) {
           
Log.d(TAG, "Failed to send initialization message", t);
         
}
       
},
        mainExecutor
);
 
}

 
@Override
 
public void onSessionTransferred(SessionId sessionId) {
   
Log.d(TAG, "Transfer done.");
 
}

 
@Override
 
public void onTransferFailure(SessionId sessionId, SessionException exception) {
   
// Handle error
 
}
}

開始工作階段轉移後,接收端裝置會收到回呼 在 onNewIntent(intent: Intent) 方法中定義。意圖資料包含所有項目 轉移工作階段所需的資訊。

如要在接收裝置上完成轉移作業,請按照下列步驟操作:

KotlinJava
private lateinit var sessions: Sessions

override fun onCreate(savedInstanceState: Bundle?) {
 
super.onCreate(savedInstanceState)
  sessions
= Sessions.create(context = this)
}

override fun onNewIntent(intent: Intent) {
 
super.onNewIntent(intent)
  lifecycleScope
.launchWhenResumed {
   
val receivingSession =
      sessions
.getReceivingSession(intent, HelloWorldReceivingSessionStateCallback())

   
// Get info from receiving device and init.
   
val startupRemoteConnection = receivingSession.getStartupRemoteConnection()

    startupRemoteConnection
.registerReceiver(
     
object : SessionConnectionReceiver {
       
override fun onMessageReceived(participant: SessionParticipant, payload: ByteArray) {
          lifecycleScope
.launchWhenResumed {
           
val transferInfo = String(payload)
            startupRemoteConnection
.send("ok".toByteArray(UTF_8))
           
// Complete transfer.
           
Log.d(TAG, "Transfer info: " + transferInfo)
            receivingSession
.onComplete()
         
}
       
}
     
}
   
)
 
}
}

private inner class HelloWorldReceivingSessionStateCallback : ReceivingSessionStateCallback {
 
override fun onTransferFailure(sessionId: SessionId, exception: SessionException) {
   
// Handle error
 
}
}
private Sessions sessions;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
 
super.onCreate(savedInstanceState);
  sessions
= Sessions.create(/* context= */ this);
}

@Override
public void onNewIntent(Intent intent) {
 
super.onNewIntent(intent);
 
ListenableFuture<ReceivingSession> receivingSessionFuture =
      sessions
.getReceivingSessionFuture(intent, new HelloWorldReceivingSessionStateCallback());
 
ListenableFuture<Void> registerReceiverFuture =
     
Futures.transform(
          receivingSessionFuture
,
          receivingSession
-> {
           
SessionRemoteConnection startupRemoteConnection =
                receivingSession
.getStartupRemoteConnection();
           
SessionConnectionReceiver receiver =
               
(participant, payload) -> {
                 
Log.d(
                      TAG
,
                     
"Successfully received initialization message of size: " + payload.length);
                  applicationInitialization
(receivingSession, payload);
               
};
            startupRemoteConnection
.registerReceiver(receiver);
           
return null;
         
},
          mainExecutor
);
 
Futures.addCallback(
      registerReceiverFuture
,
     
new FutureCallback<Void>() {
       
@Override
       
public void onSuccess(Void unused) {
         
Log.d(TAG, "Connection receiver registerd successfully");
       
}

       
@Override
       
public void onFailure(Throwable t) {
         
Log.w(TAG, "Failed to register connection receiver", t);
       
}
     
},
      mainExecutor
);
}

private void applicationInitialization(ReceivingSession receivingSession, byte[] initMessage) {
 
ListenableFuture<SessionId> disconnectFuture =
     
Futures.transform(
          receivingSession
.onCompleteFuture(),
          sessionId
-> {
           
Log.d(TAG, "Succeeded to complete receive transfer for: " + sessionId);
           
return sessionId;
         
},
          mainExecutor
);
 
Futures.addCallback(
      disconnectFuture
,
     
new FutureCallback<SessionId>() {
       
@Override
       
public void onSuccess(SessionId result) {
         
Log.d(TAG, "Succeeded to remove the old session: " + result);
       
}

       
@Override
       
public void onFailure(Throwable t) {
         
Log.d(TAG, "Failed to remove the old session, which is now orphaned", t);
       
}
     
},
      mainExecutor
);
}

private static class HelloWorldReceivingSessionStateCallback
   
implements ReceivingSessionStateCallback {
 
@Override
 
public void onTransferFailure(SessionId sessionId, SessionException exception) {
   
// Handle error
 
}
}

接收裝置後,即可繼續提供使用者體驗。

共用工作階段

分享課程即可邀請附近的其他人加入群組 操作起來,例如:

  • 直接與朋友的車分享地圖位置。
  • 與您騎單車的對象分享週日單車路線。
  • 即使手機不在身邊,也能收集團體美食訂單的物品。
  • 票選下一部電視節目,讓大家一起觀看。

當使用者選擇與其他裝置共用工作階段時,來源 裝置搜尋並顯示可加入工作階段的裝置,以及 使用者選取接收裝置。應用程式會提示使用者 接收裝置,以便從來源裝置加入工作階段。接收 裝置就會獲得次要工作階段,與裝置上的工作階段互動 。應用程式也可以將其他參與者新增至 。

共用工作階段的程序與轉移工作階段類似 而是呼叫 shareSession,而不是呼叫 transferSession。另一個 差異在於工作階段狀態回呼方法。

KotlinJava
// Originating side.
private val HELLO_WORLD_SHARE_ACTION = "hello_world_share"
private var activePrimarySession: PrimarySession? = null
private lateinit var sessions: Sessions

override fun onCreate(savedInstanceState: Bundle?) {
 
super.onCreate(savedInstanceState)
  sessions
= Sessions.create(context = this)
}

suspend fun shareSession() {
 
val sessionId = sessions.createSession(ApplicationSessionTag("hello_world_share"))
  activePrimarySession
=
    sessions
.shareSession(
      sessionId
,
     
StartComponentRequest.Builder()
       
.setAction(HELLO_WORLD_SHARE_ACTION)
       
.setReason("Share reason here")
       
.build(),
      emptyList
(),
     
HelloWorldShareSessionStateCallback(),
   
)
}

private inner class HelloWorldShareSessionStateCallback : PrimarySessionStateCallback {

 
override fun onShareInitiated(sessionId: SessionId, numPotentialParticipants: Int) {
   
// Custom logic here for when n devices can potentially join.
   
// e.g. if there were 0, cancel/error if desired,
   
//      if non-0 maybe spin until numPotentialParticipants join etc.
 
}

 
override fun onParticipantJoined(sessionId: SessionId, participant: SessionParticipant) {
   
// Custom join logic here
    lifecycleScope
.launchWhenResumed {
     
// Example logic: send only to the participant who just joined.
     
val connection =
        checkNotNull
(activePrimarySession).getSecondaryRemoteConnectionForParticipant(participant)
      connection
.send("Initing hello, world.".toByteArray(UTF_8))
      connection
.registerReceiver(
       
object : SessionConnectionReceiver {
         
override fun onMessageReceived(participant: SessionParticipant, payload: ByteArray) {
           
val ok = payload.contentEquals("ok".toByteArray(UTF_8))
           
Log.d(TAG, "Session share initialized. ok=$ok")

           
// Example logic: broadcast to all participants, including the one
           
// that just joined.
            lifecycleScope
.launchWhenResumed {
              checkNotNull
(activePrimarySession)
               
.broadcastToSecondaries("hello, all.".toByteArray(UTF_8))
           
}
         
}
       
}
     
)
   
}
 
}

 
override fun onParticipantDeparted(sessionId: SessionId, participant: SessionParticipant) {
   
// Custom leave logic here.
 
}

 
override fun onPrimarySessionCleanup(sessionId: SessionId) {
   
// Custom cleanup logic here.
    activePrimarySession
= null
 
}

 
override fun onShareFailureWithParticipant(
    sessionId
: SessionId,
    exception
: SessionException,
    participant
: SessionParticipant
 
) {
   
// Handle error
 
}
}
// Originating side
private static final String HELLO_WORLD_SHARE_ACTION = "hello_world_share";
@Nullable private PrimarySession activePrimarySession = null;
private Sessions sessions;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
 
super.onCreate(savedInstanceState);
  sessions
= Sessions.create(/* context= */ this);
}

private void shareSession() {
 
SessionId sessionId = sessions.createSession(new ApplicationSessionTag("hello_world_share"));
 
ListenableFuture<PrimarySession> shareSessionFuture =
      sessions
.shareSessionFuture(
          sessionId
,
         
new StartComponentRequest.Builder()
             
.setAction(HELLO_WORLD_SHARE_ACTION)
             
.setReason("Share reason here")
             
.build(),
         
Collections.emptyList(),
         
new HelloWorldShareSessionStateCallback());
 
Futures.addCallback(
      shareSessionFuture
,
     
new FutureCallback<PrimarySession>() {
       
@Override
       
public void onSuccess(PrimarySession primarySession) {
          activePrimarySession
= primarySession;
       
}

       
@Override
       
public void onFailure(Throwable t) {
         
Log.d(TAG, "Failed to share session", t);
       
}
     
},
      mainExecutor
);
}

private class HelloWorldShareSessionStateCallback implements PrimarySessionStateCallback {
 
@Override
 
public void onShareInitiated(SessionId sessionId, int numPotentialParticipants) {
   
// Custom logic here for when n devices can potentially join.
   
// e.g. if there were 0, cancel/error if desired,
   
//      if non-0 maybe spin until numPotentialParticipants join etc.
 
}

 
@Override
 
public void onParticipantJoined(SessionId sessionId, SessionParticipant participant) {
   
PrimarySession joinedSession = activePrimarySession;
   
if (joinedSession == null) {
     
return;
   
}
   
SessionRemoteConnection connection =
        joinedSession
.getSecondaryRemoteConnectionForParticipant(participant);
   
Futures.addCallback(
        connection
.sendFuture("Initiating hello, world.".getBytes()),
       
new FutureCallback<Void>() {
         
@Override
         
public void onSuccess(Void result) {
           
// Send successful.
         
}

         
@Override
         
public void onFailure(Throwable t) {
           
// Failed to send.
         
}
       
},
        mainExecutor
);
    connection
.registerReceiver(
       
new SessionConnectionReceiver() {
         
@Override
         
public void onMessageReceived(SessionParticipant participant, byte[] payload) {
           
boolean ok = new String(payload, UTF_8).equals("ok");
           
Log.d(TAG, "Session share initialized. ok=" + ok);

           
// Example logic: broadcast to all participants, including the one
           
// that just joined.
           
Futures.addCallback(
                joinedSession
.broadcastToSecondariesFuture("hello, all.".getBytes()),
               
new FutureCallback<Void>() {
                 
@Override
                 
public void onSuccess(Void result) {
                   
// Broadcast successful.
                 
}

                 
@Override
                 
public void onFailure(Throwable t) {
                   
// Failed to broadcast hello world.
                 
}
               
},
                mainExecutor
);
         
}
       
});
 
}

 
@Override
 
public void onParticipantDeparted(SessionId sessionId, SessionParticipant participant) {
   
// Custom leave logic here.
 
}

 
@Override
 
public void onPrimarySessionCleanup(SessionId sessionId) {
   
// Custom cleanup logic here.
    activePrimarySession
= null;
 
}

 
@Override
 
public void onShareFailureWithParticipant(
     
SessionId sessionId, SessionException exception, SessionParticipant participant) {
   
// Custom error handling logic here.
 
}
}

在接收端:

KotlinJava
// Receiving side.

override fun onNewIntent(intent: Intent) {
 
super.onNewIntent(intent)
  lifecycleScope
.launchWhenResumed {
   
val secondarySession =
      sessions
.getSecondarySession(intent, HelloWorldSecondaryShareSessionStateCallback())
   
val remoteConnection = secondarySession.getDefaultRemoteConnection()

    remoteConnection
.registerReceiver(
     
object : SessionConnectionReceiver {
       
override fun onMessageReceived(participant: SessionParticipant, payload: ByteArray) {
         
Log.d(TAG, "Payload received: ${String(payload)}")
       
}
     
}
   
)
 
}
}

private inner class HelloWorldSecondaryShareSessionStateCallback : SecondarySessionStateCallback {
 
override fun onSecondarySessionCleanup(sessionId: SessionId) {
   
// Custom cleanup logic here.
 
}
}
// Receiving side.
@Override
public void onNewIntent(Intent intent) {
 
super.onNewIntent(intent);
  sessions
= Sessions.create(this);
 
ListenableFuture<SecondarySession> secondarySessionFuture =
      sessions
.getSecondarySessionFuture(
          intent
, new HelloWorldSecondaryShareSessionStateCallback());
 
Futures.addCallback(
      secondarySessionFuture
,
     
new FutureCallback<SecondarySession>() {
       
@Override
       
public void onSuccess(SecondarySession secondarySession) {
         
SessionRemoteConnection remoteConnection =
              secondarySession
.getDefaultRemoteConnection();
          remoteConnection
.registerReceiver(
             
new SessionConnectionReceiver() {
               
@Override
               
public void onMessageReceived(SessionParticipant participant, byte[] payload) {
                 
Log.d(TAG, "Payload received: " + new String(payload, UTF_8));
               
}
             
});
       
}

       
@Override
       
public void onFailure(Throwable t) {
         
// Handle error.
       
}
     
},
      mainExecutor
);
}

private static class HelloWorldSecondaryShareSessionStateCallback
   
implements SecondarySessionStateCallback {
 
@Override
 
public void onSecondarySessionCleanup(SessionId sessionId) {
   
// Custom cleanup logic here.
 
}
}