SDK 런타임 UI 프레젠테이션 API

SDK 런타임에서는 광고 SDK가 샌드박스 환경에서 실행될 수 있으므로 게시자의 뷰 계층 구조에 액세스할 수 없습니다. 광고를 표시하기 위해 플랫폼은 SandboxedSdkProvider.getView API를 SDK에 노출하여 광고 뷰를 가져오고 이를 SurfacePackage로 패키징하여 IPC(프로세스 간 통신)를 통해 클라이언트 애플리케이션으로 전송합니다. 여기에는 몇 가지 단점이 있으며 아래에서 설명합니다. 그런 다음 이 문서에서는 이러한 문제를 해결하기 위해 빌드되고 있는 제안된 Jetpack 라이브러리를 제시합니다.

플랫폼 API 보강의 근거

프레임워크 API는 유연성을 위해 설계되었으며 UI 프레젠테이션을 위한 앱과 SDK 간 부채널을 빌드하는 작업은 앱과 SDK에 맡깁니다. 이 부채널은 다음을 실행합니다.

  1. SDK가 전체 기간 동안 여러 광고 뷰를 관리하고, SDK에서 만들어진 광고 UI가 어떻게 되는지 파악할 수 있게 해 줍니다.
  2. 뷰 생성과 콘텐츠 결합을 분리합니다. 부채널을 사용하면 SDK가 앱에 대한 광고 요청에 해당하는 객체(콘텐츠)를 반환할 수 있으며 이는 앱에서 적절하다고 판단될 때마다 광고 컨테이너에 결합될 수 있습니다.
  3. 여러 프로세스에서 UI를 표시하는 데 사용되는 기본 플랫폼 구성을 추상화합니다. 플랫폼은 현재 SurfaceControlViewhost를 사용하고 이로부터 SurfacePackage를 생성합니다.
  4. 광고 컨테이너의 UI가 변경될 때 SDK 런타임의 광고 SDK가 자동으로 알림을 수신하도록 사용 설정합니다. 게시자가 광고 컨테이너의 레이아웃을 변경해도 게시자가 명시적으로 API를 호출하여 알림을 보내지 않는 한 SDK는 이러한 변경사항을 인식하지 못합니다.
  5. 사용자에게 표시되는 버벅거림 없이 광고 UI와 광고 컨테이너의 크기 조절을 동기화합니다.
  6. 이전 버전과의 호환성을 자동으로 관리합니다. SurfacePackage는 API 수준 30 전에는 사용할 수 없습니다. 또한 SDK 런타임이 없고 SDK가 게시자에 대해 프로세스 로컬인 기기에서는 SDK에서 뷰를 직접 가져올 수 있는 경우 광고의 SurfacePackage를 만드는 것은 낭비입니다. 부채널은 SDK 및 앱 개발자 코드에서 이러한 복잡성을 추상화합니다.
  7. 광고 UI가 컴포저블과 원활하게 통합되도록 지원합니다. 뷰를 사용하지 않는 Jetpack Compose 개발자도 뷰를 계속 사용하는 SDK 개발자가 생성한 UI를 계속 호스팅할 수 있습니다.

UI 라이브러리

UI 라이브러리는 위에서 설명한 복잡성을 추상화하고 게시자와 SDK가 프로세스 전반에 걸쳐 UI를 표시하고 사용자가 UI 및 기기와 상호작용할 때 업데이트된 상태를 유지하는 데 사용할 수 있는 부채널을 제공합니다.

핵심, 클라이언트, 제공자라는 세 가지 UI 라이브러리가 있습니다. 핵심 라이브러리는 클라이언트 및 제공자 라이브러리에서 사용되는 인터페이스를 제공합니다. UI 제공자(일반적으로 SDK)는 제공자 라이브러리에 종속되고 UI 소비자(일반적으로 게시자)는 클라이언트 라이브러리에 종속됩니다. 클라이언트 라이브러리와 제공자 라이브러리는 함께 UI 세션을 만들고 유지하는 데 필요한 부채널을 형성합니다.

API

SDK 런타임 UI 프레젠테이션용 API는 다음과 같습니다.

SandboxedUiAdapter: SDK에서 만들어 게시자의 UI에 표시할 콘텐츠를 가져오는 방법을 제공합니다.

SandboxedSdkView: 게시자가 만드는 컨테이너로, SandboxedUiAdapter를 통해 얻은 콘텐츠를 보유합니다.

Session: SandboxedUiAdapter.openSession()에 대한 응답으로 SDK에서 만들어집니다. 하나의 UI 세션 호출을 나타냅니다. 이는 SDK와 게시자 간의 통신 터널의 SDK 측을 형성하고 창 분리, 크기 조절 또는 구성 변경과 같은 SandboxedSdkView 변경사항에 관한 알림을 수신합니다.

SessionClient: 클라이언트 라이브러리에서 생성되며 SDK와 게시자 간 통신 터널의 게시자 측을 형성합니다.

SandboxedSdkUiSessionStateChangedListener: 게시자가 만듭니다. SandboxedSdkView와 연결된 UI 세션 상태의 변경사항 리스너입니다.

SDK 런타임 UI 프레젠테이션 API 관계를 보여주는 그림
그림 1. SDK 런타임 UI 프레젠테이션 API 간의 관계

이러한 API에 관한 자세한 내용은 privacysandbox-ui 참조 문서를 확인하세요.

제어 흐름

다음 다이어그램은 다양한 시나리오에서 클라이언트 UI 라이브러리와 제공자 UI 라이브러리 간의 상호작용을 보여줍니다.

그림 1에서는 게시자가 프로그래매틱 방식으로 또는 XML을 통해 SandboxedSdkView를 만들고 SDK에서 정의한 API를 통해 SDK에서 얻은 SdkSandboxUiAdapter에 이를 연결하는 방법을 보여줍니다. 모든 UI 상태 변경사항을 관찰하려면 게시자는 SdkSandboxUiAdapter를 연결하기 전에 SandboxedSdkViewSandboxedSdkUiSessionStateChangedListener를 추가해야 합니다.

열린 세션 프로세스를 보여주는 그림
그림 2. SDK에서 UI를 가져옵니다.

그림 2에서는 게시자의 활동이 구성 변경을 처리하는 경우 클라이언트 라이브러리가 구성 변경사항을 SDK에 전달하여 적절하게 UI를 업데이트할 수 있도록 하는 방법을 보여줍니다. 예를 들어 이 흐름은 사용자가 기기를 회전하고 게시자가 android:configChanges=["orientation"]을 설정하여 활동의 구성 변경 처리를 선언하면 트리거될 수 있습니다.

그림 3. 게시자가 시작한 UI 변경

그림 3은 SDK가 SessionClient의 메서드를 사용하여 광고 컨테이너의 변경을 요청할 수 있는 방법을 보여줍니다. 이 API는 SDK가 광고 크기를 조절하려고 하고 새 크기를 수용하기 위해 게시자가 광고 컨테이너 크기를 조절해야 할 때 트리거됩니다. 이는 mraid.resize()와 같은 사용자 상호작용에 대한 응답으로 발생할 수 있습니다.

그림 4. SDK에서 시작된 UI 변경

그림 4에서는 SandboxedSdkView가 창에서 분리될 때 세션이 닫히는 방식을 보여줍니다. 또한 세션은 SessionClient.onSessionError()를 호출하여 SDK에 의해 언제든지(예: 사용자가 네트워크 연결이 끊긴 경우) 닫힐 수 있습니다.

그림 5. UI 세션 닫기

Z 순서

클라이언트 UI 라이브러리는 내부적으로 SurfaceView를 사용하여 SDK의 UI를 호스팅합니다. SurfaceView는 Z 순서를 사용하여 게시자의 창 위나 아래에 UI를 표시할 수 있습니다. 이는 불리언 setOnTop을 허용하는 SandboxedSdkView.orderProviderUiAboveClientUi() 메서드로 제어됩니다.

setOnToptrue이면 SandboxedSdkView의 모든 android.view.MotionEvent가 SDK로 전송됩니다. false인 경우 게시자에게 전송됩니다. 기본적으로 모션 이벤트는 SDK로 전송됩니다.

일반적으로 게시자는 광고 뷰의 기본 Z 순서를 변경하지 않아도 됩니다. 그러나 드롭다운 메뉴와 같이 광고를 가리는 UI를 표시하는 경우 Z 순서는 일시적으로 기본값에서 전환되었다가 가리는 UI 요소가 닫히면 복원되어야 합니다. 클라이언트 UI 라이브러리에서 이 프로세스를 자동화하는 방법을 모색하고 있습니다.

스크롤

광고 UI가 게시자 창 위에 Z 순서로 지정되면 광고 UI의 MotionEvents가 SDK로 전송됩니다. 광고 UI에서 시작된 스크롤 및 플링 동작은 다음과 같이 특별하게 처리됩니다.

  1. 세로 스크롤 및 플링 동작이 게시자의 컨테이너로 전송되고 게시자의 컨테이너에 의해 처리됩니다. 이렇게 하면 광고 UI가 배치된 게시자의 컨테이너가 세로로 스크롤될 수 있는 경우 우수한 UX가 제공됩니다. 이때 SDK 또는 게시자 측에서 추가 작업을 하지 않아도 됩니다.
  2. 가로 스크롤 및 플링 동작이 SDK로 전송되고 SDK에 의해 처리됩니다. 이렇게 하면 광고 UI 자체가 가로로 스크롤될 수 있는 경우(예: 광고 캐러셀) 우수한 UX가 제공됩니다.

구현 가이드

SDK는 다음을 구현해야 합니다.

1.SandboxedUiAdapter**: 이는 loadAd와 같은 SDK 정의 API에 대한 응답으로 게시자에 반환됩니다. 이 구현의 openSession() 메서드는 SDK 서버에 광고를 요청하고 이 요청에 대한 광고 뷰를 준비하는 데 사용해야 합니다. 1.Session**: SandboxedUiAdapter.openSession 호출에 대한 응답으로 반환됩니다. 클라이언트 라이브러리가 광고 UI를 가져오고 이 API의 변경사항을 SDK에 알리는 방법을 제공합니다. 모든 Session 메서드는 여기에 구현해야 합니다.

게시자는 다음을 실행해야 합니다.

  1. XML을 사용하거나 프로그래매틱 방식으로 SandboxedSdkView를 만듭니다.
  2. SandboxedSdkUiSessionStateChangedListenerSandboxedSdkView에 연결하여 UI의 변경사항을 관찰합니다.
  3. SDK 제공 SandboxedUiAdapterSandboxedSdkView에 연결합니다.
  4. 평소와 같이 창에 SandboxedSdkView를 추가하고 클라이언트 라이브러리가 SDK로 UI 세션을 만들고 유지관리하도록 허용합니다.
  5. 적절한 때에 SandboxedSdkUiSessionChangedListener에서 보고된 상태 변경에 반응합니다. 예를 들어 SDK가 예기치 않게 세션을 닫으면 게시자는 SandboxedSdkView를 정적 이미지로 바꾸거나 뷰 계층 구조에서 삭제할 수 있습니다.
  6. 드롭다운 메뉴와 같이 광고 UI를 가릴 수 있는 전환을 실행할 때는 일시적으로 orderProviderUiAboveClientUi를 false로 설정하여 광고 UI를 게시자 창 아래에 배치합니다. 드롭다운 메뉴가 닫히면 orderProviderUiAboveClientUitrue로 호출합니다.

플랫폼 API의 미래

UI 라이브러리가 베타로 전환되면 UI 프레젠테이션과 관련된 SDK 런타임 플랫폼 API(SdkSandboxManager.requestSurfacePackage()SandbxedSdkProvider.getView())가 지원 중단될 예정입니다.

미응답 질문

  1. UI 라이브러리에서 자동으로 처리해야 하는 더 일반적인 광고 UI 사용 사례가 있나요?
  2. 광고 UI를 표시하는 데 사용하는 UI 프레임워크는 무엇인가요? 이러한 프레임워크와 UI 라이브러리를 통합하는 데 문제가 있을 것으로 예상되나요?
  3. 스크롤 가능한 게시자 컨테이너에 배치된 스크롤 가능한 광고 UI가 일반적인 사용 사례인가요? 이 경우 광고 UI 및 컨테이너의 스크롤 방향은 무엇인가요? 사용자가 광고 UI에서 스크롤을 시작하면 어떤 동작이 예상되나요?