Capgo를 위한 Channel Surfing: 런타임에 Update Channel을 전환하는 방법

TestFlight나 Google Play에서 새 build를 다운로드해 설치하라고 요청하지 않고도, 특정 사용자에게 변경 사항을 직접 배포해 바로 리뷰와 피드백을 받고 싶었던 적이 있나요?

고객이 요청한 개선 사항을 빠르게 구현할 수는 있었지만, 검증을 위해 결과를 전달하려면 모든 사용자에게 업데이트를 배포하거나(실험적인 변경에는 위험), 고객 전용 일회성 build를 만들어야 했습니다(양쪽 모두 번거로운 일이죠).

부족했던 것은 유연성이었습니다. 개발자들은 비기술 이해관계자, QA, 또는 필요할 때는 전체 사용자층처럼 서로 다른 사용자 그룹에 각기 다른 업데이트를 제공할 수 있기를 원했습니다.

production build가 작업 중인 버전으로 전환해 피드백을 받은 뒤 다시 production으로 돌아갈 방법은 없었습니다.

그것이 바로 채널 서핑 을 가능하게 합니다. 사용자 기기에 설치된 앱이 런타임에 업데이트 채널을 전환할 수 있어, 프로덕션 앱을 고정된 엔드포인트가 아니라 리뷰와 반복 작업을 위한 유연한 공간으로 바꿔줍니다. 특히 프로덕션 앱을 다루는 비기술 이해관계자가 이미 설치된 앱에서 직접 변경 사항을 테스트하고 피드백을 줄 수 있어 유용합니다.

업데이트 채널 이해하기

업데이트 채널은 Capgo이 특정 빌드에 업데이트를 타겟팅하는 방식입니다. 각 빌드는 하나의 채널과 연결되며, 그 채널이 어떤 업데이트를 받을지 결정합니다.

예를 들어, 업데이트를 preview 채널에 게시해도 사용자에게 영향을 주지 않습니다 production. 과거에는 채널을 전환하려면 다른 Native Build를 설치하거나 대시보드에서 기기 할당을 수동으로 변경해야 했습니다.

Capgo의 채널을 사용하면 다음을 할 수 있습니다:

특정 사용자 그룹을 대상으로 다른 기능 제공
사용자를 다른 채널에 할당해 A/B 테스트 실행
새 기능을 점진적으로 배포
베타 테스트 프로그램 구축
개별 사용자와 프로덕션 이슈 디버깅

업데이트 채널에 익숙하지 않다면, Capgo 채널 문서에서 더 자세히 확인할 수 있습니다.

Channel Surfing이란 무엇인가요?

Channel surfing을 사용하면 설치된 앱이 재설치하지 않고도 서로 다른 업데이트 스트림에서 업데이트를 가져올 수 있습니다. 설치된 앱은 런타임에 업데이트 채널을 전환할 수 있고, 앱이 제거되거나 다른 채널로 전환될 때까지 새로 선택한 채널에서 계속 업데이트를 받습니다.

실제로 이는 제품 소유자나 QA가 production 빌드를 예를 들어 preview 특정 채널로 전환해 최신 변경 사항을 테스트할 수 있습니다. 테스트가 끝나면 다시 production 전환하면 됩니다. 재설치나 별도의 프리뷰 빌드가 필요 없습니다.

내부적으로 channel surfing은 앱이 업데이트 클라이언트에 사용할 채널을 알려주는 방식으로 동작합니다. 이 선택은 런타임에 변경할 수 있으며, 해제되거나 교체될 때까지 유지됩니다.

채널 서핑 구현 방법

채널 서핑을 사용해 보려면 프로젝트에 Capgo Live Updates가 구성되어 있어야 합니다. 설정하려면 다음을 따르세요: Capgo 퀵스타트 가이드.

채널 서핑에 필요한 설정은 Capgo dashboard에서 전환하려는 각 채널의 “Allow devices to self associate” 옵션을 활성화하는 것뿐입니다. 그 외에 별도의 code 변경이나 설정 수정은 필요하지 않습니다.

채널 서핑의 핵심은 단 하나의 API 호출로 이루어집니다:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

await CapacitorUpdater.setChannel({ channel: 'your-channel' });

이 호출은 업데이트를 위해 Capgo에 쿼리할 때 사용할 채널을 설정합니다. setChannel API에 대해 자세히 알아보기.

즉각적인 채널 전환 (v5.34.0+)

플러그인 버전 5.34.0, 6.34.0, 7.34.0 또는 8.0.0부터 (사용 중인 메이저 버전에 따라 다름), setChannel() 작동 방식이 다르고 훨씬 빠릅니다:

백엔드 검증 (읽기 전용): 채널 허용 여부를 확인하기 위해 Capgo 백엔드로 요청을 보냅니다
로컬 스토리지 업데이트: 검증이 통과되면 해당 채널을 기기 로컬 스토리지에 저장합니다
즉각적인 적용: 다음 업데이트 체크 시 즉시 새 채널을 사용합니다

기존 방식: setChannel() 채널 오버라이드 설정을 백엔드 데이터베이스에 저장했습니다 (Dashboard 또는 API 변경 사항과 동일). 이 경우 기기가 새 채널을 인식하기까지 백엔드 복제 시간(최대 2분)을 기다려야 했습니다. 이제는 백엔드에서 검증을 위해 읽기만 하고 로컬에 저장하므로 채널 전환이 즉시 이루어집니다.

전체 채널 전환 흐름

더 나은 사용자 경험을 위해, 단순히 채널을 바꾸고 앱 재시작을 기다리는 것 이상의 작업이 필요할 수 있습니다. 일반적인 방식은 즉시 업데이트를 확인하고, 사용 가능한 경우 다운로드한 뒤 앱을 다시 로드하여 사용자가 선택한 채널의 업데이트 버전으로 바로 진입하게 하는 것입니다.

일반적인 흐름은 다음과 같습니다:

채널 변경 (setChannel)
업데이트 확인 (getLatest)
업데이트 가져오기 및 적용 (download, set 또는 next)
필요하면 앱 다시 로드 (reload)

다음은 전체 예시입니다:

import { CapacitorUpdater } from '@capgo/capacitor-updater';

async function switchChannel(selectedChannel: string) {
  try {
    // 1. Set the updates channel (with optional auto-update trigger)
    await CapacitorUpdater.setChannel({
      channel: selectedChannel,
      triggerAutoUpdate: true // Immediately check for updates
    });

    console.log(`Switched to channel: ${selectedChannel}`);

    // If you want more control, handle the update manually:
    // const latest = await CapacitorUpdater.getLatest();
    // if (latest.url) {
    //   const bundle = await CapacitorUpdater.download({
    //     url: latest.url,
    //     version: latest.version
    //   });
    //   await CapacitorUpdater.set({ id: bundle.id });
    // }

  } catch (error) {
    console.error('Failed to switch channel:', error);
  }
}

// Switch to the beta channel
switchChannel('beta');

이 흐름을 어떻게 구성할지는 여러분에게 달려 있습니다. 각 단계를 여러 인터랙션으로 나누거나 한 번에 실행할 수도 있습니다. 어떻게 구성하든 실패 상황을 반드시 고려하세요. 네트워크 문제나 유효하지 않은 채널 때문에 업데이트가 적용되지 않을 수 있습니다.

유일한 요구 사항: Self-Assignment 활성화

채널 서핑 기능을 사용하기 위해 해야 할 일은 단 하나뿐입니다. 앱이 다음을 사용하여 채널을 전환하기 전에 setChannel()Capgo 대시보드에서 해당 채널의 self-assignment를 활성화해야 합니다:

다음으로 이동하세요: 채널 Capgo 대시보드의 섹션
관리하려는 채널 이름을 클릭합니다
활성화 “기기 자체 연결 허용” 옵션을
변경 사항 저장

채널 설정에서 self-assignment 활성화

끝입니다. 앱의 설정을 변경하거나 defaultChannel 추가 설정도 필요 없습니다. 사용자가 전환하길 원하는 채널에서 self-assignment만 활성화하세요.

이 설정이 비활성화되어 있으면, 해당 채널로 setChannel() 호출을 시도할 때 실패하며 channelPrivate 이벤트가 발생합니다.

사용 가능한 채널 목록

직접 할당 가능한 채널 목록을 가져올 수 있습니다:

const { channels } = await CapacitorUpdater.listChannels();

console.log('Available channels:', channels.map(c => c.name));
// Use this to build a channel selector UI

이 작업은 self-assignment가 활성화된 채널만 반환합니다.

현재 채널 가져오기

디바이스에 현재 할당된 채널을 확인하려면:

const { channel } = await CapacitorUpdater.getChannel();

console.log('Current channel:', channel);

기본 채널로 되돌리기

채널 오버라이드를 제거하고 기본 상태로 돌아가려면:

await CapacitorUpdater.unsetChannel({});

이 명령은 디바이스와 특정 채널 간의 연결을 해제하여, defaultChannel 설정 파일이나 클라우드 기본값으로 되돌립니다.

채널 서핑 테스트 방법

To see channel surfing in action, you’ll need a release build - the @capgo/capacitor-updater API is designed for release builds. In debug builds, the app typically loads JavaScript from a development server instead, which bypasses the normal update flow.

사전 요구사항

채널 서핑을 위해 필요한 유일한 설정은 “기기 자체 연결 허용” 옵션을 전환을 허용하려는 각 채널에서 활성화하는 것입니다. 앱에서 별도 설정을 변경할 필요는 없습니다.

테스트 빌드 생성하기

평소처럼 앱을 빌드하세요:

bun run build && npx cap sync

그다음 Xcode나 Android Studio로 네이티브 빌드를 생성하거나 CI/CD pipeline을 사용하세요. 앱은 Capgo dashboard에서 클라우드 기본값으로 설정된 채널로 시작됩니다.

다른 채널에 업데이트 게시하기

앱이 설치되면 다른 채널에 업데이트를 게시하세요:

# Publish to preview channel
npx @capgo/cli@latest bundle upload --channel preview

# Publish to production channel
npx @capgo/cli@latest bundle upload --channel production

그런 다음 앱의 채널 서핑 UI로 이동해 채널 전환을 트리거하세요. 앱은 선택한 채널에서 업데이트를 가져와 새 업데이트로 다시 로드해야 합니다.

채널 스위처 UI 구축하기

채널 서핑은 보통 앱을 사용하는 모든 사용자가 아니라 제한된 사용자에게만 노출하는 기능입니다. 예를 들어, 인증된 직원에게만 앱을 preview 채널로 전환하는 버튼을 제공할 수 있습니다.

다음은 채널 스위처용 React 컴포넌트 예시입니다:

import { useState, useEffect } from 'react';
import { CapacitorUpdater } from '@capgo/capacitor-updater';

export function ChannelSwitcher() {
  const [currentChannel, setCurrentChannel] = useState<string>('');
  const [availableChannels, setAvailableChannels] = useState<string[]>([]);
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    loadChannelInfo();
  }, []);

  async function loadChannelInfo() {
    const { channel } = await CapacitorUpdater.getChannel();
    setCurrentChannel(channel || 'default');

    const { channels } = await CapacitorUpdater.listChannels();
    setAvailableChannels(channels.map(c => c.name));
  }

  async function handleChannelSwitch(channel: string) {
    setIsLoading(true);
    try {
      await CapacitorUpdater.setChannel({
        channel,
        triggerAutoUpdate: true
      });
      setCurrentChannel(channel);
      // App will update in background or on next restart
    } catch (error) {
      console.error('Failed to switch channel:', error);
    } finally {
      setIsLoading(false);
    }
  }

  return (
    <div>
      <p>Current channel: {currentChannel}</p>
      <div>
        {availableChannels.map(channel => (
          <button
            key={channel}
            onClick={() => handleChannelSwitch(channel)}
            disabled={isLoading || channel === currentChannel}
          >
            Switch to {channel}
          </button>
        ))}
      </div>
    </div>
  );
}

OTA 업데이트 시 주의사항

이 문제들은 채널 전환에만 국한된 것은 아니지만, 런타임에 채널 전환을 시작하면 금방 드러나는 경향이 있습니다.

런타임 버전 불일치

Capgo의 업데이트는 네이티브 앱 버전에 연결됩니다. 업데이트의 네이티브 버전이 설치된 앱의 네이티브 버전과 일치하지 않으면 해당 업데이트는 다운로드되거나 적용되지 않습니다. 채널 전환 시에는 보통 해당 채널에 업데이트가 있어도 앱은 채널만 바뀌고 업데이트는 적용되지 않는 형태로 나타납니다.

이는 대개 업데이트가 앱의 다른 네이티브 버전에서 게시되었음을 의미합니다. 해당 채널의 bundle이 기기에 설치된 네이티브 버전과 호환되는지 확인하세요.

업데이트 삭제 및 되돌리기

앱이 이미 특정 채널의 업데이트를 다운로드한 경우, Capgo dashboard에서 해당 업데이트를 삭제해도 이미 해당 업데이트가 있는 기기에서는 제거되지 않습니다. 삭제는 향후 다운로드만 중단합니다.

잘못된 업데이트를 되돌리는 가장 확실한 방법은 동일한 채널에 정상 동작이 확인된 업데이트를 게시하는 것입니다. 이렇게 하면 채널 히스토리 최상단에 새 업데이트가 생성되며, 클라이언트는 이를 최신 버전으로 간주하고 대신 적용합니다.

Capgo은 클라이언트가 이전 안정 업데이트를 다시 적용하거나 빌드에 포함된 업데이트로 돌아가도록 지시할 수 있는 롤백 메커니즘도 제공합니다.

데이터 마이그레이션 고려 사항

채널을 전환하면 앱이 실행하는 JavaScript bundle이 변경됩니다. 만약 앱이 채널 간 호환되지 않는 마이그레이션이나 데이터 구조에 의존하고 있다면, 채널을 빈번하게 전환할 때 문제가 발생할 수 있습니다.

예를 들어, 베타 업데이트에서 데이터베이스 마이그레이션을 수행했다면 프로덕션 버전은 새로운 스키마를 인식하지 못할 수 있습니다. 개발자는 업데이트 간 전환이 안전하도록 설계하거나, 필요한 경우 전환 방향을 한쪽으로 제한해야 합니다.

채널 서핑이 모바일 반복 개발을 개선하는 이유

채널 서핑(Channel surfing)은 프로덕션 환경에서 변경 사항을 빠르게 검토해야 할 때 특히 유용합니다.

빠른 검증

광범위하게 배포하기 전 검증이 필요한 긴급 버그 수정 상황을 가정해 보세요. 채널 서핑을 사용하면, 변경 사항을 특정 사용자 그룹에만 격리하여 프로덕션에 반영되기 전 미리 검토할 수 있습니다.

이해관계자 리뷰

제품 담당자(PO)나 QA는 설치된 프로덕션 빌드를 다른 업데이트 채널로 전환하여 수정 사항이나 기능을 확인한 뒤, 작업이 끝나면 다시 원래 채널로 돌아올 수 있습니다.

효율적인 테스트

이를 통해 워크플로우를 매끄럽게 유지하면서도 비개발 직군 이해관계자를 검토 및 의사결정 과정에 쉽게 참여시킬 수 있습니다. 단일 프로덕션 빌드가 테스트, 피드백, 검증을 위한 유연한 도구가 되는 것입니다.

사용 사례

QA 테스트: QA 팀이 기능 브랜치 간 전환 가능
베타 프로그램: 사용자가 조기 액세스를 위해 베타 채널 선택
이해관계자 리뷰: 제품 담당자가 출시 전 변경 사항 미리보기
A/B 테스트: 실험을 위해 사용자를 서로 다른 채널에 할당
디버깅: 문제 진단을 위해 특정 사용자를 디버그 채널로 전환

비교: 채널 변경 방식

메서드	적용 시간	저장 위치	사용 사례
`setChannel()` 플러그인으로부터	즉시	기기 전용 (로컬)	앱 내 사용자 주도 채널 전환
대시보드 기기 오버라이드	최대 2분	백엔드 데이터베이스	특정 기기에 대한 관리자 주도 변경
API 채널 할당	최대 2분	백엔드 데이터베이스	자동화된 백엔드 통합

채널 전환 UI를 구축할 때 최상의 사용자 경험을 제공하려면 항상 플러그인의 setChannel() method를 사용하세요.

모범 사례

액세스 제한: 채널 서핑은 주로 내부용입니다. 모든 사용자에게 노출하지 마세요.
에러 처리: 채널을 전환할 때는 항상 에러를 유연하게 처리해야 합니다.
호환성 검증: 서로 다른 채널의 업데이트가 설치된 Native Build 버전과 호환되는지 확인하세요.
채널 문서화: 각 채널의 용도를 명확히 문서화하세요
사용량 모니터링: 디버깅을 위해 어떤 디바이스가 어떤 채널에 있는지 추적하세요

리소스

마치며

채널 서핑을 통해 Capacitor 앱의 반복 개발 방식이 완전히 바뀝니다. 프로덕션 빌드를 고정된 엔드포인트로 취급하는 대신, 테스트와 검증, 빠른 반복 개발을 위한 유연한 도구로 활용할 수 있습니다.

최신 플러그인 버전에서 도입된 즉각적인 채널 전환 기능 덕분에 이제 끊김 없는 경험이 가능합니다. 사용자는 채널을 전환하자마자 대기 시간 없이 새 채널의 업데이트를 즉시 받을 수 있습니다.

이해관계자와 버그 수정을 검증하거나, 베타 프로그램을 운영하거나, 특정 사용자와 함께 문제를 디버깅할 때, 채널 서핑을 활용하면 적절한 시점에 적절한 사용자에게 정확한 업데이트를 배포할 수 있는 유연성을 얻게 됩니다.

Channel Surfing for Capgo에서 이어서: 런타임에 Update Channel을 전환하는 방법

사용 중이라면 Capgo를 위한 Channel Surfing: 런타임에 Update Channel을 전환하는 방법 채널 라우팅과 단계적 배포를 계획하려면, 다음을 연결하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: 채널 Channels의 구현 세부 사항은 다음을 참고하세요: Beta Testing 솔루션 Beta Testing 솔루션의 제품 워크플로우를 위한, 그리고 버전 타겟팅 솔루션 Version Targeting Solution의 제품 워크플로우용.