이 페이지는 Cloud Translation API를 통해 번역되었습니다.

앱의 맞춤 빠른 설정 타일 만들기

빠른 설정은 빠른 설정 패널에 표시되는 타일로, 사용자가 탭하여 반복되는 작업을 빠르게 완료할 수 있는 작업을 나타냅니다. 앱은 TileService 클래스를 통해 사용자에게 맞춤 카드를 제공하고 Tile 객체를 사용하여 카드의 상태를 추적할 수 있습니다. 예를 들어 사용자가 앱에서 제공하는 VPN을 사용 설정하거나 사용 중지할 수 있는 카드를 만들 수 있습니다.

카드를 만들 시점 결정

사용자가 자주 액세스하거나 빠르게 액세스해야 하는 기능 (또는 둘 다)의 카드를 만드는 것이 좋습니다. 가장 효과적인 카드는 이러한 두 가지 특성을 모두 충족하여 자주 실행하는 작업에 빠르게 액세스할 수 있는 카드입니다.

예를 들어 사용자가 운동 세션을 빠르게 시작할 수 있는 피트니스 앱의 카드를 만들 수 있습니다. 하지만 사용자가 전체 운동 기록을 검토할 수 있는 동일한 앱의 카드를 만드는 것은 권장하지 않습니다.

피트니스 앱 카드 사용 사례 — **그림 2.** 피트니스 앱의 추천 카드와 비추천 카드의 예시

카드의 검색 가능성과 사용 편의성을 개선하려면 다음과 같은 관행을 피하는 것이 좋습니다.

카드를 사용하여 앱을 실행하지 마세요. 대신 앱 바로가기 또는 표준 런처를 사용하세요.
일회성 사용자 작업에는 카드를 사용하지 마세요. 대신 앱 바로가기 또는 알림을 사용하세요.
카드를 너무 많이 만들지 않습니다. 앱당 최대 2개를 사용하는 것이 좋습니다. 대신 앱 바로가기를 사용하세요.
정보를 표시하지만 사용자와 상호작용이 불가능한 카드는 사용하지 마세요. 대신 알림이나 위젯을 사용하세요.

카드 만들기

카드를 만들려면 먼저 적절한 카드 아이콘을 만든 다음 앱의 매니페스트 파일에서 TileService를 만들고 선언해야 합니다.

빠른 설정 샘플에서는 타일을 만들고 관리하는 방법의 예를 제공합니다.

맞춤 아이콘 만들기

빠른 설정 패널의 타일에 표시되는 맞춤 아이콘을 제공해야 합니다. 다음 섹션에 설명된 대로 TileService를 선언할 때 이 아이콘을 추가합니다. 아이콘은 투명한 배경에 흰색 단색이어야 하며, 크기는 24x24dp여야 하고 VectorDrawable 형식이어야 합니다.

타일의 목적을 시각적으로 암시하는 아이콘을 만듭니다. 이렇게 하면 사용자가 카드가 자신의 요구사항에 적합한지 쉽게 파악할 수 있습니다. 예를 들어 사용자가 운동 세션을 시작할 수 있는 피트니스 앱의 카드에 스톱워치 아이콘을 만들 수 있습니다.

TileService 만들기 및 선언

TileService 클래스를 확장하는 카드의 서비스를 만듭니다.

Kotlin

class MyQSTileService: TileService() {

  // Called when the user adds your tile.
  override fun onTileAdded() {
    super.onTileAdded()
  }
  // Called when your app can update your tile.
  override fun onStartListening() {
    super.onStartListening()
  }

  // Called when your app can no longer update your tile.
  override fun onStopListening() {
    super.onStopListening()
  }

  // Called when the user taps on your tile in an active or inactive state.
  override fun onClick() {
    super.onClick()
  }
  // Called when the user removes your tile.
  override fun onTileRemoved() {
    super.onTileRemoved()
  }
}

자바

public class MyQSTileService extends TileService {

  // Called when the user adds your tile.
  @Override
  public void onTileAdded() {
    super.onTileAdded();
  }

  // Called when your app can update your tile.
  @Override
  public void onStartListening() {
    super.onStartListening();
  }

  // Called when your app can no longer update your tile.
  @Override
  public void onStopListening() {
    super.onStopListening();
  }

  // Called when the user taps on your tile in an active or inactive state.
  @Override
  public void onClick() {
    super.onClick();
  }

  // Called when the user removes your tile.
  @Override
  public void onTileRemoved() {
    super.onTileRemoved();
  }
}

앱의 매니페스트 파일에서 TileService를 선언합니다. TileService의 이름과 라벨, 이전 섹션에서 만든 맞춤 아이콘, 적절한 권한을 추가합니다.

 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"  // 18-character limit.
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>

TileService 관리

앱 매니페스트에서 TileService를 만들고 선언한 후에는 상태를 관리해야 합니다.

TileService는 바인드된 서비스입니다. TileService는 앱에서 요청하거나 시스템에서 통신해야 하는 경우 바인딩됩니다. 일반적인 바인드된 서비스 수명 주기에는 onCreate(), onBind(), onUnbind(), onDestroy()라는 4개의 콜백 메서드가 포함됩니다. 이러한 메서드는 서비스가 새 수명 주기 단계에 진입할 때마다 시스템에서 호출합니다.

TileService 수명 주기 개요

바인드된 서비스 수명 주기를 제어하는 콜백 외에도 TileService 수명 주기에 관한 다른 메서드를 구현해야 합니다. Service 수명 주기 메서드와 TileService 수명 주기 메서드는 두 개의 별도의 비동기 스레드에서 호출되므로 이러한 메서드는 onCreate() 및 onDestroy() 외부에서 호출될 수 있습니다.

TileService 수명 주기에는 다음 메서드가 포함되며, 이 메서드는 TileService가 새 수명 주기 단계에 진입할 때마다 시스템에서 호출합니다.

onTileAdded(): 이 메서드는 사용자가 카드를 처음 추가할 때만 호출되며 사용자가 카드를 삭제했다가 다시 추가하는 경우에도 호출됩니다. 일회성 초기화를 실행하기에 가장 좋은 시점입니다. 그러나 이렇게 하면 필요한 모든 초기화가 충족되지 않을 수 있습니다.

참고: onTileAdded()는 카드가 생성될 때마다 호출되지 않습니다. 예를 들어 기기의 전원이 꺼지기 전에 카드가 추가되었고 삭제되지 않은 경우 기기가 재부팅되거나 전원이 켜질 때 onTileAdded()이 호출되지 않습니다.
onStartListening() 및 onStopListening(): 앱이 카드를 업데이트할 때마다 호출되며 자주 호출됩니다. TileService는 onStartListening()와 onStopListening() 사이에 바인딩된 상태로 유지되므로 앱에서 카드를 수정하고 업데이트를 푸시할 수 있습니다.
onTileRemoved(): 사용자가 카드를 삭제하는 경우에만 이 메서드가 호출됩니다.

청취 모드 선택

TileService는 활성 모드 또는 비활성 모드에서 리슨합니다. 앱 매니페스트에서 선언해야 하는 활성 모드를 사용하는 것이 좋습니다. 그렇지 않으면 TileService가 표준 모드이며 선언할 필요가 없습니다.

TileService가 onStartListening() 및 onStopListening() 메서드 쌍 외부에 있다고 가정하지 마세요.

활성 모드 (권장)

자체 프로세스에서 상태를 수신 대기하고 모니터링하는 TileService에는 활성 모드를 사용합니다. 활성 모드의 TileService는 onTileAdded(), onTileRemoved(), 탭 이벤트에 바인딩되며 앱 프로세스에서 요청할 때도 바인딩됩니다.

카드 상태가 자체 프로세스에 의해 업데이트되어야 할 때 TileService에 알림이 전송되는 경우 활성 모드를 사용하는 것이 좋습니다. 활성 카드는 빠른 설정 패널이 사용자에게 표시될 때마다 바인딩할 필요가 없으므로 시스템의 부담을 줄입니다.

정적 TileService.requestListeningState() 메서드를 호출하여 수신 대기 상태 시작을 요청하고 onStartListening() 콜백을 수신할 수 있습니다.

앱의 매니페스트 파일에 META_DATA_ACTIVE_TILE를 추가하여 활성 모드를 선언할 수 있습니다.

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
         android:value="true" />
    ...
</service>

비활성 모드

비활성 모드는 표준 모드입니다. 카드가 사용자에게 표시될 때마다 바인딩되는 경우 TileService는 비활성 모드입니다. 즉, 제어할 수 없는 시점에 TileService가 다시 생성되고 바인딩될 수 있습니다. 또한 사용자가 카드를 보고 있지 않을 때는 바인딩이 해제되고 카드가 소멸될 수 있습니다.

사용자가 빠른 설정 패널을 연 후 앱은 onStartListening()에 대한 콜백을 수신합니다. onStartListening()와 onStopListening() 간에 Tile 객체를 원하는 횟수만큼 업데이트할 수 있습니다.

비활성 모드는 선언할 필요가 없습니다. 앱의 매니페스트 파일에 META_DATA_ACTIVE_TILE를 추가하지 않으면 됩니다.

카드 상태 개요

사용자가 카드를 추가하면 카드는 항상 다음 상태 중 하나에 있습니다.

STATE_ACTIVE: 사용 설정 또는 사용 중지 상태를 나타냅니다. 이 상태에서는 사용자가 카드와 상호작용할 수 있습니다.

예를 들어 사용자가 시간 제한이 있는 운동 세션을 시작할 수 있는 피트니스 앱 카드의 경우 STATE_ACTIVE은 사용자가 운동 세션을 시작했고 타이머가 실행 중임을 의미합니다.
STATE_INACTIVE: 꺼짐 또는 일시중지 상태를 나타냅니다. 이 상태에서는 사용자가 카드와 상호작용할 수 있습니다.

피트니스 앱 카드 예를 다시 사용해 보면 STATE_INACTIVE의 카드는 사용자가 운동 세션을 시작하지 않았지만 원하는 경우 시작할 수 있음을 의미합니다.
STATE_UNAVAILABLE: 일시적으로 사용할 수 없는 상태를 나타냅니다. 이 상태에서는 사용자가 타일과 상호작용할 수 없습니다.

예를 들어 STATE_UNAVAILABLE의 카드는 어떤 이유로든 현재 사용자가 카드를 사용할 수 없음을 의미합니다.

주의: 현재 사용할 수 없지만 나중에 사용 가능한 상태로 전환될 수 있는 카드에는 STATE_UNAVAILABLE를 사용합니다. 사용자가 더 이상 구성요소를 사용할 수 없는 경우 COMPONENT_ENABLED_STATE_DISABLED를 setComponentEnabledSetting()에 전달합니다.

시스템은 Tile 객체의 초기 상태만 설정합니다. 나머지 수명 주기 동안 Tile 객체의 상태를 설정합니다.

시스템은 Tile 객체의 상태를 반영하기 위해 카드 아이콘과 배경을 색조 조정할 수 있습니다. STATE_ACTIVE로 설정된 Tile 객체가 가장 어둡고 STATE_INACTIVE 및 STATE_UNAVAILABLE가 점점 더 밝아집니다. 정확한 색조는 제조업체와 버전에 따라 다릅니다.

객체 상태를 반영하도록 색조가 지정된 VPN 타일 — **그림 4.** 카드 상태 (활성, 비활성, 사용 불가 상태)를 반영하도록 색조가 지정된 카드의 예시입니다.

카드 업데이트

onStartListening() 콜백을 수신하면 카드를 업데이트할 수 있습니다. 타일의 모드에 따라 onStopListening() 콜백을 수신할 때까지 타일이 한 번 이상 업데이트될 수 있습니다.

활성 모드에서는 onStopListening() 콜백을 수신하기 전에 카드를 정확히 한 번 업데이트할 수 있습니다. 비활성 모드에서는 onStartListening()과 onStopListening() 사이에서 카드를 원하는 횟수만큼 업데이트할 수 있습니다.

getQsTile()를 호출하여 Tile 객체를 검색할 수 있습니다. Tile 객체의 특정 필드를 업데이트하려면 다음 메서드를 호출합니다.

Tile 객체의 필드를 올바른 값으로 설정했다면 updateTile()를 호출하여 카드를 업데이트해야 합니다. 이렇게 하면 시스템에서 업데이트된 카드 데이터를 파싱하고 UI를 업데이트합니다.

Kotlin

data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)

override fun onStartListening() {
  super.onStartListening()
  val state = getStateFromService()
  qsTile.label = state.label
  qsTile.contentDescription = tile.label
  qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.icon = state.icon
  qsTile.updateTile()
}

자바

public class StateModel {
  final boolean enabled;
  final String label;
  final Icon icon;

  public StateModel(boolean e, String l, Icon i) {
    enabled = e;
    label = l;
    icon = i;
  }
}

@Override
public void onStartListening() {
  super.onStartListening();
  StateModel state = getStateFromService();
  Tile tile = getQsTile();
  tile.setLabel(state.label);
  tile.setContentDescription(state.label);
  tile.setState(state.enabled ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setIcon(state.icon);
  tile.updateTile();
}

탭 처리

카드가 STATE_ACTIVE 또는 STATE_INACTIVE에 있으면 사용자는 카드를 탭하여 작업을 트리거할 수 있습니다. 그런 다음 시스템은 앱의 onClick() 콜백을 호출합니다.

앱이 onClick() 콜백을 수신하면 대화상자 또는 활동을 실행하거나 백그라운드 작업을 트리거하거나 카드의 상태를 변경할 수 있습니다.

Kotlin

var clicks = 0
override fun onClick() {
  super.onClick()
  counter++
  qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.label = "Clicked $counter times"
  qsTile.contentDescription = qsTile.label
  qsTile.updateTile()
}

자바

int clicks = 0;

@Override
public void onClick() {
  super.onClick();
  counter++;
  Tile tile = getQsTile();
  tile.setState((counter % 2 == 0) ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setLabel("Clicked " + counter + " times");
  tile.setContentDescription(tile.getLabel());
  tile.updateTile();
}

대화상자 실행

showDialog(): 빠른 설정 패널을 접고 대화상자를 표시합니다. 추가 입력이나 사용자 동의가 필요한 경우 대화상자를 사용하여 작업에 컨텍스트를 추가합니다.

활동 시작

startActivityAndCollapse()는 패널을 접는 동안 활동을 시작합니다. 활동은 대화상자 내에 표시할 정보가 더 많거나 작업이 매우 상호작용적인 경우에 유용합니다.

앱에 상당한 사용자 상호작용이 필요한 경우 앱은 최후의 수단으로만 활동을 실행해야 합니다. 대신 대화상자 또는 전환 버튼을 사용하는 것이 좋습니다.

타일을 길게 탭하면 사용자에게 앱 정보 화면이 표시됩니다. 이 동작을 재정의하고 대신 환경설정 활동을 실행하려면 ACTION_QS_TILE_PREFERENCES를 사용하여 활동 중 하나에 <intent-filter>를 추가합니다.

Android API 28부터 PendingIntent에는 Intent.FLAG_ACTIVITY_NEW_TASK가 있어야 합니다.

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
}

또는 특정 Activity 섹션의 AndroidManifest.xml에 플래그를 추가할 수 있습니다.

카드를 전환 가능하도록 표시

카드가 주로 2상태 스위치 (카드의 가장 일반적인 동작)로 작동하는 경우 전환 가능한 카드로 표시하는 것이 좋습니다. 이렇게 하면 운영체제에 카드의 동작에 관한 정보를 제공하고 전반적인 접근성을 개선하는 데 도움이 됩니다.

TOGGLEABLE_TILE 메타데이터를 true로 설정하여 카드를 전환 가능하도록 표시합니다.

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

안전하게 잠긴 기기에서만 안전한 작업 실행

잠긴 기기의 잠금 화면 상단에 타일이 표시될 수 있습니다. 카드에 민감한 정보가 포함된 경우 isSecure() 값을 확인하여 기기가 안전한 상태인지 확인하고 TileService가 그에 따라 동작을 변경해야 합니다.

잠긴 상태에서 카드 작업을 실행해도 안전한 경우 startActivity()를 사용하여 잠금 화면 위에 활동을 실행합니다.

카드 작업이 안전하지 않은 경우 unlockAndRun()를 사용하여 사용자에게 기기를 잠금 해제하라는 메시지를 표시합니다. 성공하면 시스템은 이 메서드에 전달한 Runnable 객체를 실행합니다.

사용자에게 카드 추가 메시지 표시

사용자가 카드를 직접 추가하려면 다음 단계를 따라야 합니다.

아래로 스와이프하여 빠른 설정 패널을 엽니다.
수정 버튼을 탭합니다.
기기의 모든 타일을 스크롤하여 내 타일을 찾습니다.
타일을 길게 누른 다음 활성 타일 목록으로 드래그합니다.

사용자는 언제든지 카드를 이동하거나 삭제할 수도 있습니다.

Android 13부터 requestAddTileService() 메서드를 사용하여 사용자가 카드를 기기에 훨씬 더 쉽게 추가할 수 있습니다. 이 메서드는 사용자에게 빠른 설정 패널에 타일을 직접 추가하라는 메시지를 표시합니다. 프롬프트에는 애플리케이션 이름, 제공된 라벨, 아이콘이 포함됩니다.

빠른 설정 배치 API 프롬프트 — **그림 5.** 빠른 설정 배치 API 메시지

public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

콜백에는 타일이 추가되었는지 여부, 추가되지 않았는지 여부, 이미 있었는지 여부 또는 오류가 발생했는지 여부에 관한 정보가 포함됩니다.

사용자에게 메시지를 표시할 시점과 빈도를 결정할 때는 재량권을 사용하세요. requestAddTileService()는 카드에서 제공하는 기능과 사용자가 처음 상호작용할 때와 같이 컨텍스트에서만 호출하는 것이 좋습니다.

사용자가 이전에 충분히 거부한 경우 시스템은 특정 ComponentName의 요청 처리를 중지할 수 있습니다. 사용자는 이 서비스를 검색하는 데 사용된 Context에서 결정되며 현재 사용자와 일치해야 합니다.