Capgo 채널 스루핑: 런타임에서 업데이트 채널을 Switch하는 방법

사용자가 즉시 검토 및 피드백을 받을 수 있도록, 테스트 플라이트나 구글 플레이에서 새로운 빌드를 다운로드하고 설치하지 않고 직접 변경을 배포할 수 있는 방법이 있나요?

저는 고객이 요청한 개선 사항을 빠르게 구현할 수 있었습니다. 그러나 결과를 고객이 검증할 수 있도록 배포하는 것은 실험적인 변경이 위험하므로 모든 사용자에게 업데이트를 배포하거나 고객에게만 특정한 빌드를 생성하는 것은 모두에게 부담이 될 수 있었습니다.

개발자들은 다양한 사용자 그룹에 대해 다른 업데이트를 제공할 수 있는 유연성을 원했습니다. 예를 들어 비기술적인 이해관계자, QA, 또는 적절한 경우 전체 사용자 기반.

생산 빌드가 워크 인 프로그레스 버전으로 전환할 수 없고, 피드백을 수집하고, 그리고 다시 생산으로 돌아갈 수 없었다.

그것이 채널 전환 을 통해 가능합니다. 사용자의 장치에 설치된 앱은 런타임에서 업데이트 채널을 전환할 수 있으므로, 생산 앱을 검토 및 반복의 유연한 공간으로 변환할 수 있습니다. 비기술적인 이해관계자가 생산 앱을 사용하여 변경을 테스트하고 직접 피드백을 제공할 수 있도록 해줍니다.

업데이트 채널 이해

업데이트 채널은 Capgo이 특정 빌드에 대한 업데이트를 받도록 하는 방법입니다. 각 빌드는 채널과 관련되어 있으며, 채널은 해당 채널이 받을 업데이트를 결정합니다.

예를 들어, __CAPGO_KEEP_0__에서 업데이트를 특정 채널에 게시할 수 있습니다. 이 경우 사용자에게 영향을 미치지 않습니다. preview 채널을 변경하는 경우 이전에는 다른 네이티브 빌드를 설치하거나 직접 대시보드에서 장치 할당을 수동으로 변경해야 했습니다. production__CAPGO_KEEP_0__의 채널은 다음과 같은 기능을 제공합니다:

Channels in Capgo allow you to:

A/B 테스트를 위해 사용자를 다른 채널에 할당
새로운 기능을 점진적으로 출시
베타 테스트 프로그램을 생성
개별 사용자에 대한 프로덕션 문제를 디버그
업데이트 채널에 대해 익숙하지 않은 경우 __CAPGO_KEEP_0__ 채널 문서를 참조하세요.

__CAPGO_KEEP_0__ Capgo __CAPGO_KEEP_0__

What is Channel Surfing?

Channel surfing은 설치된 앱이 재설치 없이 다른 업데이트 스트림으로 pull 할 수 있도록 해줍니다. 설치된 앱은 런타임에 업데이트 채널을 switch 할 수 있고, 새로 선택한 채널에서 업데이트를 계속 받을 것입니다. 앱이 삭제되거나 다른 채널로 switch 될 때까지.

실제로, 이 의미는 제품 소유자 또는 QA가 예를 들어, production 채널로 switch 할 수 있고, 최신 변경 사항을 테스트 할 수 있습니다. 테스트가 끝나면 다시 preview 으로 switch 할 수 있습니다. 재설치나 별도의 미리보기 빌드가 필요하지 않습니다. production 채널 서핑의 내부 동작은 앱이 업데이트 클라이언트에 사용할 채널을 알려주는 것입니다. 이 선택은 런타임에 변경 될 수 있고, 삭제되거나 대체 될 때까지 유지됩니다.

Channel Surfing 구현 방법

Channel 서핑을 시도하기 전에, 프로젝트가 __CAPGO_KEEP_0__ Live Updates와 함께 구성되어 있어야 합니다. 설정 방법은

Capgo quickstart guide 채널 서핑을 위해 필요한 설정은 Capgo dashboard에서 'Allow devices to self associate'를 각 채널에 대해 활성화하는 것입니다..

Capgo covers them in more detail. No code 변경이나 설정 수정이 필요합니다.

채널 스루핑의 핵심은 단일 API 호출에 의해 구동됩니다.

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

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

This sets the channel that is used when querying Capgo for updates. API setChannel에 대해 더 알아보세요..

채널 전환 (v5.34.0+)

플러그인 버전 5.34.0, 6.34.0, 7.34.0, 또는 8.0.0 (대형 버전에 따라 달라짐)부터 채널 전환은 다음과 같이 작동합니다. setChannel() 백엔드 유효성 검사 (읽기 전용)

: __CAPGO_KEEP_0__ 백엔드에 요청을 보내 채널이 허용되는지 유효성 검사합니다.: A request is sent to the Capgo backend to validate the channel is allowed
: 유효성 검사 통과 시, 채널은 장치의 로컬 스토리지에 저장됩니다.Instant Channel Switching (v5.34.0+)
즉시 효과: 새로운 채널을 사용하기 위해 다음 업데이트 확인이 즉시 사용됩니다.

그전에는 setChannel() API의 변경 사항과 같은 백엔드 데이터베이스에 채널 오버라이드 저장했습니다. 장치들은 새로운 채널이 인식되기까지 백엔드 복제를 기다려야했습니다 (2분까지). 새로운 동작은 백엔드에서만 읽고(유효성 검사용) 지역 저장소에만 저장합니다, 따라서 채널 Switching이 즉시 발생합니다.

채널 Switching Flow

사용자 경험을 개선하기 위해, 채널 Switch만하고 다음 앱 리스타트를 기다리기만 하는 것보다 더 많은 작업을 수행하는 것이 일반적입니다. 일반적인 접근 방식은 즉시 업데이트 확인, 다운로드(만약 업데이트 가능하다면), 앱 리로드를 수행하여 사용자가 선택한 채널의 업데이트 페이지로 직접 이동하는 것입니다.

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

채널 변경 (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');

이 흐름을 어떻게 구조화할지는 당신의 선택입니다. 이러한 단계를 여러 상호 작용에 걸쳐 나누거나 한 번에 모두 실행할 수 있습니다. 흐름의 구조는 무엇이든 간에, 실패를 고려하도록 하세요. 네트워크 문제나 유효하지 않은 채널은 모두 업데이트가 적용되지 않도록 할 수 있습니다.

만족하는 조건: 자체 할당 활성화

자체 할당 활성화만 하면 채널 스루핑을 활성화할 수 있습니다. 앱이 채널을 switch하기 전에 setChannel()를 사용하려면, 채널의 자체 할당을 Capgo 대시보드에서 활성화해야 합니다.

__CAPGO_KEEP_0__ 대시보드의 채널 section in your Capgo dashboard
관리하고 싶은 채널 이름을 클릭하세요.
활성화 “기기들이 자체적으로 연결되도록 허용하세요.”
변경을 저장하세요

채널 설정에서 자체 할당을 활성화하세요

그의 끝입니다. 앱에서 설정 변경이 필요하지 않습니다. defaultChannel 사용자가 switch 할 수 있는 채널에서만 자체 할당을 활성화하세요.

이 설정이 비활성화된 경우, 이 채널을 호출하는 시도는 실패하고 setChannel() 이벤트가 발생합니다. channelPrivate 가용 채널 목록

자체 할당을 위해 사용할 수 있는 채널 목록을 가져올 수 있습니다:

이것은 자체 할당이 활성화된 채널만 반환합니다.

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

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

현재 채널 가져오기

장치가 현재 할당된 채널을 확인하세요:

이벤트가 발생합니다.

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

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

기본 채널로 되돌리기

기본 채널로 되돌아가기 위해 채널 override를 제거하려면:

await CapacitorUpdater.unsetChannel({});

이것은 기기에 특정 채널 assign를 해제하고, 기본 채널로 돌아가게 합니다. 이 경우, config에서 지정하거나 cloud 기본값을 사용합니다. defaultChannel 채널 스루핑 테스트 방법

채널 스루핑을 실제로 확인하려면, 릴리즈 빌드가 필요합니다. __CAPGO_KEEP_0__은 릴리즈 빌드에만 지원됩니다. 디버그 빌드의 경우, 앱은 일반적으로 개발 서버에서 자바스크립트를 로드하기 때문에, 일반 업데이트 흐름을 우회합니다.

기본 조건 @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.

Prerequisites

을 활성화해야 합니다. 앱에서 config 변경이 필요하지 않습니다. 테스트 빌드 생성 테스트 빌드 생성

테스트 빌드 생성

Build your app as usual:

bun run build && npx cap sync

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

다중 채널 업데이트를 위한 게시

앱이 설치된 후 다중 채널 업데이트를 게시하세요.

# 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를 만들기

채널 전환은 일반적으로 사용자에게 노출되지 않습니다. 예를 들어, 인증된 직원만이 앱을 프리뷰 채널로 전환하는 버튼을 사용할 수 있습니다.

다음은 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>
  );
}

채널 전환 Gotchas

이것들은 채널 전환과 관련이 없지만 런타임 채널 전환을 시작하면 빠르게 나타납니다.

런타임 버전 불일치

Capgo 업데이트는 네이티브 앱 버전과 결합되어 있습니다. 설치된 앱의 네이티브 버전과 업데이트의 네이티브 버전이 일치하지 않으면 업데이트가 다운로드되거나 적용되지 않습니다. 채널 전환 시, 일반적으로 앱이 채널을 전환하지만 업데이트가 적용되지 않는데, 실제로 업데이트가 존재하는 채널에서 발생합니다.

이 경우 업데이트가 다른 네이티브 앱 버전에서 게시된 것으로 보인다. 채널의 패키지를 네이티브 버전이 설치된 장치와 호환되도록 확인하세요.

업데이트 삭제

앱이 이미 채널에 대한 업데이트를 다운로드한 경우 Capgo 대시보드에서 업데이트를 삭제하면 이미 업데이트를 다운로드한 장치에서 업데이트를 삭제하지 않습니다. 삭제는 미래 다운로드만 중단합니다.

업데이트가 잘못된 경우 가장 신뢰할 수 있는 방법은 동일한 채널에 알려진 좋은 업데이트를 게시하는 것입니다. 이로 인해 채널의 역사 상단에 새로운 업데이트가 생성되고, 클라이언트는 이 업데이트를 최신 버전으로 처리하여 대신 적용합니다.

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

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

채널 Switching은 앱이 실행하는 자바스크립트 패키지를 변경합니다. 데이터 형태나 마이그레이션에 의존하는 앱이 채널 간에 호환되지 않는 경우 채널을 전환하면 문제가 발생할 수 있습니다.

예를 들어, 베타 업데이트가 데이터베이스 마이그레이션을 적용하면 프로덕션 버전은 새로운 스키마를 이해하지 못할 수 있습니다. 개발자는 업데이트가 채널을 전환할 수 있는지 여부를 확인해야 하며, 필요할 때는 전환을 한 방향으로 제한해야 합니다.

채널 전환은 특히 프로덕션 환경에서 변경 사항을 빠르게 검토할 때 유용합니다.

업데이트 삭제

Rapid Validation

긴급 버그 수정이 널리 배포되기 전에 검증이 필요할 때 생각해 보세요. 채널 스루핑을 통해 변경 사항은 지정된 사용자만이 검토하기 전에 프로덕션에 도달하기 전에 작은 그룹으로 분리할 수 있습니다.

Stakeholder Review

제품 소유자 또는 QA 팀원은 설치된 프로덕션 빌드를 다른 업데이트 채널로 Switch하고, 수정 또는 기능을 검증하고, 작업이 끝나면 다시 Switch할 수 있습니다.

Streamlined Testing

이것은 비기술적인 이해관계자들이 검토 및 결정을 내리는데 참여하는 것을 더 쉽게 만듭니다. 단일 프로덕션 빌드는 테스트, 피드백 및 검증을위한 유연한 도구가 됩니다.

Use Cases

QA Testing: QA 팀이 기능 branch 사이를 Switch할 수 있습니다.
Beta Programs: 사용자가 베타 채널에 가입하여 이른 접근을 받을 수 있습니다.
Stakeholder Review: 제품 소유주가 출시 전 변경 사항을 미리 볼 수 있습니다.
A/B Testing: 사용자를 실험을 위한 다른 채널에 할당합니다.
Debugging: 특정 사용자를 디버그 채널로 전환하여 문제를 진단합니다.

Comparison: 채널 변경 방법

방법	효과 시간	저장 위치	사용 사례
`setChannel()` 플러그인에서	즉시	__CAPGO_KEEP_0__ 기기만 (로컬)	사용자가 앱 내에서 채널 switching을 시작할 때
기기 오버라이드	최대 2분	백엔드 데이터베이스	특정 기기에 대한 관리자가 시작한 변경 사항
API 채널 assign	최대 2분	백엔드 데이터베이스	자동화된 백엔드 통합

채널 switching UI를 빌드할 때 최상의 사용자 경험을 위해, 항상 플러그인의 method를 사용하세요. setChannel() method.

최선의 관행

권한 제한: 채널 전환은 일반적으로 내부 용도로 사용되며 모든 사용자에게 노출되지 않아야 합니다
오류 처리: 채널 전환 시 오류를 무마하는 것이 항상 좋습니다
호환성 확인: 설치된 네이티브 버전과 호환되는지 업데이트된 채널의 호환성을 확인합니다
채널 문서화: 각 채널의 목적을 명확하게 문서화합니다
사용량 모니터링: 디버깅을 위해 장치가 어느 채널에 있는지 추적합니다

자원

결론

Capacitor 앱을 개발할 때 채널 스루핑은 큰 변화를 가져옵니다. 프로덕션 빌드가 고정된 엔드포인트가 아닌 유연한 도구로 사용되기 때문입니다. 테스트, 검증, 및 빠른 반복을 위해.

최근 플러그인 버전에서 소개된 즉시 채널 Switching은 사용자 경험을 완벽하게 만들었습니다. 사용자는 채널을 Switch하고 즉시 새로운 채널에서 업데이트를 받을 수 있습니다. 기다리는 시간이 없습니다.

버그 수정을 검증하는 데 스테이크 홀더와 함께, 베타 프로그램을 실행하거나 특정 사용자와 문제를 디버깅하는 등, 채널 스루핑은 사용자에게 필요한 업데이트를 정확한 시간에 제공할 수 있게 해줍니다.

Capgo 채널 스루핑에 대해 계속 진행하세요: 런타임에서 업데이트 채널 Switch하기

__CAPGO_KEEP_0__을 사용하는 경우 Capgo 채널 스루핑: 런타임에서 업데이트 채널 Switch하기 를 사용하여 채널 라우팅과 스테이지드 롤아웃을 계획하고 연결하세요. 채널 채널에 대한 구현 세부 정보를 위해 채널 채널에 대한 구현 세부 정보를 위해 채널 채널에 대한 구현 세부 정보를 위해 베타 테스트 솔루션 제품 워크플로우에서 베타 테스트 솔루션을 위해 버전 대상 솔루션 제품 워크플로우에서 버전 대상 솔루션을 위해

Capgo 채널을 동적으로 Switch하는 방법: 채널 전환

업데이트 채널 이해

What is Channel Surfing?

Channel 서핑을 시도하기 전에, 프로젝트가 __CAPGO_KEEP_0__ Live Updates와 함께 구성되어 있어야 합니다. 설정 방법은

채널 전환 (v5.34.0+)

채널 Switching Flow

만족하는 조건: 자체 할당 활성화

자체 할당을 위해 사용할 수 있는 채널 목록을 가져올 수 있습니다:

장치가 현재 할당된 채널을 확인하세요:

기본 채널로 되돌리기

Prerequisites

테스트 빌드 생성

다중 채널 업데이트를 위한 게시

채널 전환 UI를 만들기

채널 전환 Gotchas

런타임 버전 불일치

업데이트 삭제

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

채널 전환은 특히 프로덕션 환경에서 변경 사항을 빠르게 검토할 때 유용합니다.

Rapid Validation

Stakeholder Review

Streamlined Testing

Use Cases

Comparison: 채널 변경 방법

최선의 관행

자원

결론

Capgo 채널 스루핑에 대해 계속 진행하세요: 런타임에서 업데이트 채널 Switch하기