Android용 스레드 네트워크 SDK

스레드 네트워크 SDK는 Threads의 디지털 스레드와 비슷한 키체인을 통해 Android 앱이 스레드 네트워크 사용자 인증 정보를 Google Play 서비스 이렇게 하면 앱이 스레드 기기를 설정할 수 있습니다. 모든 스마트 홈 생태계를 관리할 수 있습니다.

단 몇 번의 API 호출로 다음을 수행할 수 있습니다.

  1. Google Play 서비스에서 기본 스레드 네트워크 사용자 인증 정보를 요청합니다.
  2. 새 보더 라우터를 설정하고 Google에 스레드 네트워크 사용자 인증 정보 추가하기 Play 서비스
  3. 이미 필드 내 보더 라우터가 있는 경우 경계가 있는지 확인할 수 있습니다. 라우터가 선호 네트워크에 있고 필요한 경우 마이그레이션합니다.

사용자 및 개발자의 여정에는 여러 가지가 있습니다. 이 과정에서 기타 주요 기능 및 권장 사용법에 대해서도 자세히 알아보세요.

주요 용어 및 API 개념

시작하기 전에 다음 용어를 이해하는 것이 좋습니다.

  • 스레드 네트워크 사용자 인증 정보: 스레드 네트워크 이름, 네트워크 키 및 주어진 Thread 네트워크에 참여하기 위한 Thread 기기

  • Preferred Thread Network Credentials(기본 스레드 네트워크 사용자 인증 정보): 자동 선택된 스레드 네트워크 자격 증명을 사용하여 다른 공급업체의 앱과 공유할 수 있습니다. getPreferredCredentials API

  • 경계 에이전트 ID: 스레드 보더 라우터의 16바이트 전역적으로 고유한 ID입니다. 있습니다. 이 ID는 보더 라우터 공급업체에서 만들고 관리합니다.

  • 스레드 보더 라우터 설정 앱: 새 스레드 보더 라우터 장치를 연결하고, 스레드 네트워크 크리덴셜을 Google Play 서비스 앱은 추가된 액세스할 수 있어야 합니다

많은 Thread Network API는 태스크 완료되기 때문입니다 이때 addOnSuccessListener 및 addOnFailureListener 결과 수신을 위한 콜백을 등록할 수 있습니다. 자세한 내용은 태스크 문서를 참조하세요.

사용자 인증 정보 소유권 및 유지보수

스레드 네트워크 사용자 인증 정보를 추가하는 앱이 사용자 인증 정보에 액세스할 수 있는 전체 권한을 가집니다. 만약 다른 앱에서 추가한 사용자 인증 정보에 액세스하려고 하면 PERMISSION_DENIED을 받게 됩니다. 오류가 발생했습니다.

앱 소유자는 Google에 사용자 인증 정보를 저장한 상태로 스레드 보더 라우터 네트워크가 업데이트되면 Play 서비스가 최신 상태로 유지됩니다. 이 즉, 필요한 경우 자격 증명을 추가하고 경계선에 있는 경우 자격 증명을 라우터의 스레드 네트워크 크리덴셜이 변경되고 스레드 보더 라우터가 삭제되거나 초기화되었습니다.

보더 에이전트 검색

사용자 인증 정보는 국경 요원 ID로 저장해야 합니다. 이 작업이 제대로 작동하는지 스레드 보더 라우터 설정 앱에서 보더 에이전트 ID를 확인할 수 있는지 스레드 보더 라우터의 역할을 할 수 있습니다.

스레드 보더 라우터는 mDNS를 사용하여 스레드 네트워크 정보를 알려야 합니다. 네트워크 이름, 확장 팬 ID, 경계 에이전트 ID가 포함됩니다. 이 이러한 속성에 해당하는 txt 값은 nn, xp, id입니다. 각각 1개의 값으로 사용합니다.

Google 보더 라우터가 있는 네트워크의 경우 Google Play 서비스가 자동으로 사용할 Google 스레드 네트워크 사용자 인증 정보를 가져옵니다.

Android 앱에 SDK 통합

시작하려면 다음 단계를 완료하세요.

  1. 다음 페이지에 제공된 안내를 따르세요. Google Play 서비스를 설정합니다.

  2. build.gradle 파일에 Google Play 서비스 종속 항목을 추가합니다.

    implementation 'com.google.android.gms:play-services-threadnetwork:16.0.0'

  3. 선택사항: 보더 라우터를 저장할 BorderAgent 데이터 클래스 정의 확인할 수 있습니다 이 가이드 전체에서 이 데이터를 사용합니다.

    data class BorderAgentInfo(
  // Network Name max 16 len
  val networkName: String = "",
  val extPanId: ByteArray = ByteArray(16),
  val borderAgentId: ByteArray = ByteArray(16),
  ...
)

다음으로 선호하는 사용자 인증 정보를 제공합니다

새로운 보더 라우터 설정

새 보더 라우터를 위한 새 네트워크를 만들기 전에 먼저 선호하는 네트워크 사용자 인증 정보를 사용해 보시기 바랍니다. 이렇게 하면 가능한 경우 스레드 기기는 단일 스레드 네트워크에 연결됩니다.

getPreferredCredentials 호출이 실행됩니다. 사용자에게 네트워크 요청을 허용하라는 메시지를 표시합니다. 네트워크인 경우 사용자 인증 정보는 스레드 SDK 디지털 키체인에 저장되었으며, 사용자 인증 정보는 앱에 반환됩니다.

사용자 인증 정보 요청

사용자에게 기본 사용자 인증 정보를 요청하는 메시지를 표시하려면 다음 안내를 따르세요.

  1. ActivityLauncher를 선언합니다.

    private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

  2. ThreadNetworkCredentials로 반환된 Activity 결과를 처리합니다.

    preferredCredentialsLauncher =
 registerForActivityResult(
   StartIntentSenderForResult()
 ) { result: ActivityResult ->
   if (result.resultCode == RESULT_OK) {
     val threadNetworkCredentials = ThreadNetworkCredentials.fromIntentSenderResultData(result.data!!)
     Log.d("debug", threadNetworkCredentials.networkName)
   } else {
     Log.d("debug", "User denied request.")
   }
 }

  3. preferredCredentials를 호출하고 활동을 실행합니다.

    private fun getPreferredThreadNetworkCredentials() {
  ThreadNetwork.getClient(this)
    .preferredCredentials
  .addOnSuccessListener { intentSenderResult ->
    intentSenderResult.intentSender?.let {
      preferredCredentialsLauncher.launch(IntentSenderRequest.Builder(it).build())
      } ?: Log.d("debug", "No preferred credentials found.")
    }
  .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

새 스레드 네트워크 만들기

사용자의 계정에 기본 스레드 네트워크 사용자 인증 정보가 없는 경우 스레드 네트워크의 경우, addCredentials API를 사용하여 사용자 인증 정보를 Google Play 서비스 이렇게 하려면 ThreadBorderAgent, ThreadNetworkCredentials 객체도 제공합니다.

임의의 네트워크를 만들려면 newRandomizeBuilder를 호출합니다.

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder().build()

스레드 네트워크 이름을 지정하려면 다음 단계를 따르세요.

val threadCredentials = ThreadNetworkCredentials.newRandomizedBuilder()
  .setNetworkName("ThreadNetworkSDK")
  .build()

사용자 인증 정보 추가

다른 스레드 공급업체에서 스레드 네트워크 사용자 인증 정보를 사용할 수 있도록 하려면 다음 단계를 따르세요. Google Play 서비스에 추가해야 합니다. 새로운 이 스레드가 어떤 보더 라우터 장치에 있는지도 알아야 합니다. 지정할 수 있습니다

이 예시에서는 국경 요원 ID에서 ThreadBorderAgent를 만듭니다. 방금 만든 새 스레드 네트워크 사용자 인증 정보를 전달합니다.

private fun addCredentials(borderAgentInfo: BorderAgentInfo, credentialsToBeAdded: ThreadNetworkCredentials) {

  val threadBorderAgent = ThreadBorderAgent.newBuilder(borderAgentInfo.borderAgentId).build()
  Log.d("debug", "border router id:" + threadBorderAgent.id)

  ThreadNetwork.getClient(this)
    .addCredentials(threadBorderAgent, credentialsToBeAdded)
      .addOnSuccessListener {
        Log.d("debug", "Credentials added.")
      }
      .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

필드 내 보더 라우터 감지 및 마이그레이션

현재 필드 내 보더 라우터가 있는 경우 보더 라우터에 속하는지 확인하려면 isPreferredCredentials하세요. 선호 네트워크로 라우팅할 수 있습니다. 이 API는 권한을 요청하고, 보더 라우터 크리덴셜을 저장된 데이터와 비교하여 Google Play 서비스의 애플리케이션입니다.

isPreferredCredentails는 일치하지 않는 경우 0를, 일치하지 않으면 1를 반환합니다. Int 데이터 유형으로 처리됩니다. IsPreferredCredentialsResult를 사용할 수 있습니다. 결과를 확인하세요.

public @interface IsPreferredCredentialsResult {
    int PREFERRED_CREDENTIALS_NOT_FOUND = -1;
    int PREFERRED_CREDENTIALS_NOT_MATCHED = 0;
    int PREFERRED_CREDENTIALS_MATCHED = 1;
}

isPreferredCredentials 서비스를 사용하려면 다음을 만들어야 합니다. ThreadNetworkCredentials 객체를 먼저 호출합니다. ThreadNetworkCredentials를 인스턴스화하는 방법에는 여러 가지가 있습니다. 다음 단계에서는 이러한 옵션에 대해 알아봅니다.

운영 데이터 세트별 스레드 네트워크 사용자 인증 정보

스레드 보더 라우터가 Thread 네트워크를 연결하고 이 Thread 네트워크를 Google Play 서비스에 추가하려고 함 다른 공급업체와 공유할 수 있습니다. ThreadNetworkCredential를 만들 수 있습니다. 원시 스레드 활성 운영 데이터 세트 TLV 목록의 인스턴스

  1. 운영 데이터 세트를 ByteArray로 변환합니다. 예를 들면 다음과 같습니다.

    val activeDataset =
      "0e080000000000010000000300000f35060004001fffe0020833333333...".dsToByteArray()

    fun String.dsToByteArray(): ByteArray {
  return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
}

  2. fromActiveOperationalDataset를 사용하여 ThreadNetworkCredentials를 만듭니다. 성공하면 스레드 네트워크 이름, 채널, 기타 네트워크 정보가 있을 수 있습니다. 전체 속성 목록은 다음을 참조하세요. ThreadNetworkCredentials.

    val threadNetworkCredentials =
    ThreadNetworkCredentials.fromActiveOperationalDataset(activeDataset)
Log.d(
    "threadNetworkCredentials",
    threadNetworkCredentials.channel.toString() + " - " + threadNetworkCredentials.networkName)

  3. isPreferredCredentials API를 호출하고 ThreadNetworkCredentials입니다.

    ThreadNetwork.getClient(this)
.isPreferredCredentials(threadNetworkCredentials)
.addOnSuccessListener { result ->
  when (result) {
    IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_NOT_MATCHED ->
        Log.d("isPreferredCredentials", "Credentials not matched.")
    IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_MATCHED ->
        Log.d("isPreferredCredentials", "Credentials matched.")
  }
}
.addOnFailureListener { e: Exception -> Log.d("isPreferredCredentials", "ERROR: [${e}]") }

보더 에이전트의 스레드 네트워크 사용자 인증 정보

보더 에이전트 ID는 보더 라우터 기기를 고유하게 식별합니다. 사용 방법 getCredentialsByBorderAgent API를 사용하려면 먼저 ThreadBorderAgent 객체를 설정하고 국경 요원 ID를 전달합니다.

ThreadBorderAgent 객체를 만든 후에는 다음을 호출합니다. getCredentialsByBorderAgent입니다. 사용자 인증 정보가 저장되었다면 선택할 수 있습니다.

private fun isPreferredThreadNetworkByBorderAgent(borderAgentInfo: BorderAgentInfo) {

  val threadBorderAgent = ThreadBorderAgent.newBuilder(borderAgentInfo.borderAgentId).build()
  Log.d("debug", "border router id:" + threadBorderAgent.id)

  var isPreferred = IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_NOT_FOUND
  var borderAgentCredentials: ThreadNetworkCredentials?
  val taskByBorderAgent = ThreadNetwork.getClient(this)
  taskByBorderAgent
      .getCredentialsByBorderAgent(threadBorderAgent)
      .addOnSuccessListener { result: ThreadNetworkCredentialsResult ->
        borderAgentCredentials = result.credentials
        result.credentials?.let {
          taskByBorderAgent.isPreferredCredentials(it).addOnSuccessListener { result ->
            isPreferred = result
          }
        }
      }
      .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

확장 팬 ID별 스레드 네트워크 사용자 인증 정보

getPreferredCredentials와 마찬가지로 사용자에게 다음을 요청하는 메시지를 표시할 수도 있습니다. 크리덴셜을 가져옵니다. 이 getCredentialsByExtendedPanId가 IntentSender를 반환하고 Activity가 반환함 사용자가 승인하면 결과에 ThreadNetworkCredentials 객체가 포함됩니다.

private fun getCredentialsByExtPanId(borderAgentInfo: BorderAgentInfo) {
  ThreadNetwork.getClient(this)
    .getCredentialsByExtendedPanId(borderAgentInfo.extPanId)
    .addOnSuccessListener { intentSenderResult ->
      intentSenderResult.intentSender?.let {
        preferredCredentialsLauncher.launch(IntentSenderRequest.Builder(it).build())
      }
        ?: Log.d("debug", "No credentials found.")
    }
    .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

사용자 인증 정보 삭제

보더 라우터 기기를 홈에서 삭제하거나 기기를 초기화하면 Google Play 서비스에서 스레드 네트워크를 삭제해야 합니다.

private fun removeCredentials(borderAgentInfo: BorderAgentInfo) {

  val threadBorderAgent = ThreadBorderAgent.newBuilder(borderAgentInfo.borderAgentId).build()
  Log.d("debug", "border router id:" + threadBorderAgent.id)

  ThreadNetwork.getClient(this)
      .removeCredentials(threadBorderAgent)
      .addOnSuccessListener { Log.d("debug", "Credentials removed.") }
      .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

리소스

스레드 네트워크 SDK에 관한 자세한 내용은 API 참조