중국에서 Capgo 사용하기

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

중국 사용자에게 앱을 배포하는 경우, 안정적이고 빠른 업데이트를 위해 Capgo가 지역 OST(Object Storage Technology) URL을 사용하도록 설정해야 합니다.

왜 중국 전용 URL을 사용해야 하나요?

중국의 네트워크 인프라 및 규제(Great Firewall)로 인해 국제 서버로의 직접 연결은 느리거나 불안정할 수 있습니다. Capgo는 지연 시간을 최소화하고 사용자가 최대한 빠르고 안정적으로 업데이트를 받을 수 있도록 홍콩에 데이터가 위치한 전용 OST URL을 제공합니다.

설정

중국에서 Capgo를 설정하려면 Capacitor 설정 파일에 세 가지 특정 URL을 지정해야 합니다. 이 URL들은 Capgo의 홍콩 기반 인프라를 가리킵니다.

다음 capacitor.config.ts 파일

다음 설정을 CapacitorUpdater plugin 섹션에 추가하세요:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

export default config;

변경 사항을 적용하려면 앱을 다시 빌드하세요:
터미널 창
```
npm run build
npx cap sync
```

설정 상세 정보

각 URL의 역할은 다음과 같습니다:

updateUrl: https://updater.capgo.com.cn/updates - 앱의 사용 가능한 업데이트를 확인하고 다운로드하는 데 사용됩니다
statsUrl: https://updater.capgo.com.cn/stats - 분석 데이터 및 사용 통계를 Capgo로 전송하는 데 사용됩니다
channelUrl: https://updater.capgo.com.cn/channel_self - 채널 설정을 가져오고 적용할 업데이트를 결정하는 데 사용됩니다

중국 권장 설정

중국의 만리방화벽으로 인한 네트워크 성능 제한 때문에, 중국 본토에 배포되는 앱을 위한 권장 사항을 안내해 드립니다:

API 응답 타임아웃 늘리기

Capgo updater 플러그인은 다음의 경우 API 호출을 중단합니다: responseTimeout 가 초과될 때 (값의 단위는 초입니다)). Capgo 앞단의 Edge 인프라 또한 약 3초 일부 경로에 대한 실패 예산(failure budget)으로 사용됩니다.

중국 본토의 경우 국가 간 네트워크 지연 시간이 더 길 수 있습니다. 따라서 중국 배포 시에는 더 높은 responseTimeout 플러그인이 업데이트 확인 및 다운로드를 완료할 수 있도록 충분한 여유를 확보해야 합니다. updater.capgo.com.cn 조기에 실패하는 대신:

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      // Seconds. Raise above the default (20) for China network conditions.
      responseTimeout: 60,
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

백그라운드 업데이트 사용하기

저희는 사용을 강력히 권장합니다 autoUpdate: 'atBackground' 중국 내 앱의 경우 네트워크 연결 성능이 다른 지역보다 낮을 수 있습니다. 다운로드가 중단되거나 느려질 경우 instant apply 모드는 사용자 경험을 저해할 수 있습니다.

대신 업데이트가 백그라운드에서 다운로드되고 앱이 백그라운드로 전환되거나 재시작될 때 적용되는 기본 업데이트 방식을 사용하세요. 이를 통해 사용자에게 더 안정적인 경험을 제공할 수 있습니다.

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground', // Recommended for China
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

전체 설정 예시

중국에 배포되는 앱을 위한 권장 설정이 포함된 전체 예시입니다:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground', // Recommended for better reliability in China
      responseTimeout: 60, // Seconds — give China network more room
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

export default config;

설정 테스트하기

중국 전용 URL 설정을 마친 후, 업데이트가 정상적으로 작동하는지 다음과 같이 확인할 수 있습니다:

Capgo에 새 번들을 upload 하세요:

npx @capgo/cli@latest bundle upload --channel=production

중국에 있는 테스트 기기에 앱을 설치하세요
업데이트 프로세스를 모니터링하세요:
터미널 창
```
npx @capgo/cli@latest app debug
```
업데이트가 중국 OST URL에서 download 되고 있는지 확인하세요

멀티 리전 배포

앱이 중국 안팎의 사용자에게 서비스를 제공한다면, 전 세계 모든 사용자에게 중국 도메인 설정을 사용할 수 있습니다. updater.capgo.com.cn 이 도메인은 Alibaba DNS 인프라 덕분에 전 세계적으로 해석되므로, 중국 내부와 그 외 전 세계 어디서든 접속할 수 있습니다.

중국 도메인 글로벌 사용

중국 도메인 URL은 멀티 리전 앱에서 원활하게 작동합니다:

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground', // Recommended for China users
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

이 설정 하나로 다음 모두에 적용됩니다:

중국 본토 사용자 (홍콩 기반 인프라 사용)
중국 외 지역 사용자 (Alibaba DNS를 통해 동일 인프라 접속)

성능 고려 사항:

비록 .cn 도메인이 Alibaba DNS를 통해 전 세계적으로 해석되므로 어디서든 작동하지만, 표준 도메인에 비해 중국 외 지역 사용자의 성능은 약간 낮을 수 있습니다 ("api.capgo.app), which is resolved directly by Cloudflare where our backend is hosted. However, DNS resolution is fast, so the performance difference is minimal and won’t significantly impact the user experience.

대안: 지역별 설정

지역별로 다른 최적화 방식을 적용하고 싶다면 다음 방법도 고려해 보세요:

서로 다른 설정을 가진 앱 변형(variant)을 별도로 빌드하기
환경 기반 설정을 사용해 URL을 동적으로 설정하기
지역별로 별도의 릴리스 채널 생성하기

멀티 리전 배포 전략에 도움이 필요하시면 다음으로 문의해 주세요: support@capgo.app 또는 저희 Discord 커뮤니티에 for help.

중국 인프라 모니터링

Capgo의 중국 전용 엔드포인트 상태와 현황은 다음에서 모니터링할 수 있습니다: status.capgo.com.cn. 앱 문제를 해결하기 전에 이 페이지에서 중국 OST URL의 장애, 지연 시간, 가동 시간을 확인하세요.

문제 해결

중국에서 업데이트 문제가 발생한다면:

설정 확인 - 세 URL이 모두 올바르게 설정되어 있는지 다시 확인하세요: capacitor.config.ts
높이기 responseTimeout - 최소 60 초를 중국에서 사용해 업데이트 요청이 진행 중일 때 플러그인이 중단되지 않도록 하세요.
네트워크 연결 확인 - 기기에서 다음 주소에 접속할 수 있는지 확인하세요: updater.capgo.com.cn 도메인
중국 상태 페이지 확인 - 검토 status.capgo.com.cn 진행 중인 장애나 성능 저하가 있는지 확인하세요
로그 검토 - 사용 npx @capgo/cli@latest app debug 에러 메시지가 있는지 확인하세요
업데이트 테스트 - 새 bundle을 upload하고 download 과정을 모니터링하세요
고객 지원 문의 - 문제가 지속되면 다음으로 문의해 주세요 support@capgo.app 또는 저희 Discord 커뮤니티에 도움이 필요하시면

다음 단계

자세히 알아보기 업데이트 동작 업데이트 적용 시점 커스터마이즈
둘러보기 채널 다양한 릴리스 트랙 관리
검토 암호화 업데이트 보안 강화

다음 단계: 중국에서 Capgo 사용하기

사용 중이라면 중국에서 Capgo 사용하기 live update 배포를 계획하려면, 다음과 연결하세요 Capgo Live Updates Capgo Live Updates의 제품 워크플로우를 보려면, 개요 Overview의 구현 상세를 보려면, 기능 Features의 구현 상세를 보려면, 업데이트 동작 Update Behavior의 구현 세부 사항은 다음과 같고, 업데이트 유형 Update Types의 구현 세부 사항은 다음과 같습니다.