번들

복사할 수 있는 설정 지시

Capgo의 핵심 업데이트 패키지입니다. 각 번들은 웹 자산 (HTML, CSS, JS)으로 구성된 앱의 콘텐츠를 포함합니다. 번들은 API을 통해 관리할 수 있으며, 목록 및 삭제를 포함합니다.

번들 이해

특정 버전의 앱의 웹 콘텐츠를 대표하는 번들은 다음과 같은 항목을 포함합니다:

번들 (버전): Semantic 버전 번호 bundle에 대한
체크섬: 버전을 확인하기 위한 고유한 해시
저장 정보: 저장 위치와 방법에 대한 세부 정보
네이티브 요구 사항: 최소 네이티브 앱 버전 요구 사항
메타 데이터: 생성 시간, 소유권, 추적 정보

수동으로 번들 만들기 (Without CLI)

Capgo CLI을 사용하지 않고 수동으로 만들고 업로드하는 방법은 다음과 같습니다.

: 수동으로 번들을 만들고 업로드하는 방법에 대한 설명입니다. (Without __CAPGO_KEEP_0 CAPGO_KEEP_1__: )

앱의 웹 자산을 먼저 구축하세요:

npm run build

Step 2: Capgo CLI와 동일한 패키지를 사용하여 번들 ZIP을 생성하세요

중요: Capgo CLI 내부에서 사용하는 정확한 자바스크립트 패키지를 사용하여 호환성을 보장하세요.

필요한 패키지를 설치하세요

npm install adm-zip @tomasklaen/checksum

자바스크립트와 함께 ZIP 파일을 생성하세요 (Capgo와 CLI와 동일)

아래 예시에서 __CAPGO_KEEP_0__는 __CAPGO_KEEP_0__ 버전 이름을 나타냅니다. version API 버전 이름을 나타냅니다.

const fs = require('node:fs');
const path = require('node:path');
const os = require('node:os');
const AdmZip = require('adm-zip');
const { checksum: getChecksum } = require('@tomasklaen/checksum');

// Exact same implementation as Capgo CLI
function zipFileUnix(filePath) {
  const zip = new AdmZip();
  zip.addLocalFolder(filePath);
  return zip.toBuffer();
}

async function zipFileWindows(filePath) {
  console.log('Zipping file windows mode');
  const zip = new AdmZip();

  const addToZip = (folderPath, zipPath) => {
    const items = fs.readdirSync(folderPath);

    for (const item of items) {
      const itemPath = path.join(folderPath, item);
      const stats = fs.statSync(itemPath);

      if (stats.isFile()) {
        const fileContent = fs.readFileSync(itemPath);
        zip.addFile(path.join(zipPath, item).split(path.sep).join('/'), fileContent);
      } else if (stats.isDirectory()) {
        addToZip(itemPath, path.join(zipPath, item));
      }
    }
  };

  addToZip(filePath, '');
  return zip.toBuffer();
}

// Main zipFile function (exact same logic as CLI)
async function zipFile(filePath) {
  if (os.platform() === 'win32') {
    return zipFileWindows(filePath);
  } else {
    return zipFileUnix(filePath);
  }
}

async function createBundle(inputPath, outputPath, version) {
  // Create zip using exact same method as Capgo CLI
  const zipped = await zipFile(inputPath);

  // Write to file
  fs.writeFileSync(outputPath, zipped);

  // Calculate checksum using exact same package as CLI
  const checksum = await getChecksum(zipped, 'sha256');

  return {
    filename: path.basename(outputPath),
    version: version,
    size: zipped.length,
    checksum: checksum
  };
}

// Usage
async function main() {
  try {
    const result = await createBundle('./dist', './my-app-1.2.3.zip', '1.2.3');
    console.log('Bundle info:', JSON.stringify(result, null, 2));
  } catch (error) {
    console.error('Error creating bundle:', error);
  }
}

main();

3단계: CLI와 동일한 패키지를 사용하여 SHA256 체크섬 계산

const fs = require('node:fs');
const { checksum: getChecksum } = require('@tomasklaen/checksum');

async function calculateChecksum(filePath) {
  const fileBuffer = fs.readFileSync(filePath);
  // Use exact same package and method as Capgo CLI
  const checksum = await getChecksum(fileBuffer, 'sha256');
  return checksum;
}

// Usage
async function main() {
  const checksum = await calculateChecksum('./my-app-1.2.3.zip');
  console.log('Checksum:', checksum);
}

main();

4단계: 저장소에 ZIP 파일 업로드

웹에 접근 가능한 저장소에 ZIP 파일을 업로드하세요:

# Example: Upload to your server via scp
scp my-app-1.2.3.zip user@your-server.com:/var/www/bundles/

# Example: Upload to S3 using AWS CLI
aws s3 cp my-app-1.2.3.zip s3://your-bucket/bundles/

# Example: Upload via curl to a custom endpoint
curl -X POST https://your-storage-api.com/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@my-app-1.2.3.zip"

중요: __CAPGO_KEEP_0__의 __CAPGO_KEEP_0__의 서버는 HTTPS URL에서 __CAPGO_KEEP_0__를 다운로드해야 합니다. HTTPS URL(인증이 필요하지 않습니다)로 접근하여 Capgo의 서버에서 이 URL에서 패키지를 다운로드해야 합니다.

5단계: __CAPGO_KEEP_0__ __CAPGO_KEEP_1__에 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 등록

https://your-storage.com/bundles/my-app-1.2.3.zip
https://github.com/username/repo/releases/download/v1.2.3/bundle.zip
https://cdn.jsdelivr.net/gh/username/repo@v1.2.3/dist.zip

5단계: Capgo API에 Capgo API 등록

등록하려는 외부 번들을 Capgo에 직접 API 호출을 사용하여 등록하세요.

async function registerWithCapgo(appId, version, bundleUrl, checksum, apiKey) {
  const fetch = require('node-fetch');

  // Create bundle (version)
  const response = await fetch('https://api.capgo.app/bundle/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'authorization': apiKey
    },
    body: JSON.stringify({
      app_id: appId,
      version: version,
      external_url: bundleUrl,
      checksum: checksum
    })
  });

  if (!response.ok) {
    throw new Error(`Failed to create bundle: ${response.statusText}`);
  }

  const data = await response.json();
  console.log('Bundle created:', data);

  return data;
}

API 매개변수

파라미터	설명	필수
`app_id`	애플리케이션 식별자	네
`version`	버전 Semantic 버전 (예: "1.2.3")	네
`external_url`	공개적으로 접근 가능 HTTPS URL에서 버블을 다운로드할 수 있는 URL (인증 필요 없음)	네
`checksum`	SHA256 체크섬	Yes

패키지 구조 요구 사항

bundle zip은 다음 요구 사항을 충족해야 합니다.

Root Index File: 필요합니다 index.html root 수준에서
Capacitor 통합: 반드시 호출해야 합니다. notifyAppReady() in your app code
자산 경로: 상대 경로를 사용하여 모든 자산

유효한 번들 구조

bundle.zip
├── index.html
├── assets/
│   ├── app.js
│   └── styles.css
└── images/

완전한 수동 워크플로 예제

Node.js 스크립트를 사용하여 Capgo에 압축, 체크섬, 업로드하는 간단한 예제:

const fs = require('node:fs');
const os = require('node:os');
const AdmZip = require('adm-zip');
const { checksum: getChecksum } = require('@tomasklaen/checksum');
const fetch = require('node-fetch');

async function deployToCapgo() {
  const APP_ID = 'com.example.app';
  const VERSION = '1.2.3';
  const BUNDLE_URL = 'https://your-storage.com/bundles/app-1.2.3.zip';
  const API_KEY = process.env.CAPGO_API_KEY;

  // 1. Create zip (same as Capgo CLI)
  const zip = new AdmZip();
  zip.addLocalFolder('./dist');
  const zipped = zip.toBuffer();

  // 2. Calculate checksum (same as Capgo CLI)
  const checksum = await getChecksum(zipped, 'sha256');
  console.log('Checksum:', checksum);

  // 3. Upload to your storage (replace with your upload logic)
  // fs.writeFileSync('./bundle.zip', zipped);
  // ... upload bundle.zip to your storage ...

  // 4. Register with Capgo API
  const response = await fetch('https://api.capgo.app/bundle/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'authorization': API_KEY
    },
    body: JSON.stringify({
      app_id: APP_ID,
      version: VERSION,
      external_url: BUNDLE_URL,
      checksum: checksum
    })
  });

  if (!response.ok) {
    throw new Error(`Failed: ${response.statusText}`);
  }

  console.log('Bundle registered with Capgo!');
}

deployToCapgo().catch(console.error);

의존성 설치:

npm install adm-zip @tomasklaen/checksum node-fetch

체크섬 검증

자바스크립트 체크섬 계산 (Capgo CLI과 동일)

Capgo CLI이 내부적으로 사용하는 정확한 패키지와 메소드를 사용하십시오:

const fs = require('node:fs');
const { checksum: getChecksum } = require('@tomasklaen/checksum');

async function calculateChecksum(filePath) {
  const fileBuffer = fs.readFileSync(filePath);
  // Use exact same package and method as Capgo CLI
  const checksum = await getChecksum(fileBuffer, 'sha256');
  return checksum;
}

// Verify checksum matches
async function verifyChecksum(filePath, expectedChecksum) {
  const actualChecksum = await calculateChecksum(filePath);
  const isValid = actualChecksum === expectedChecksum;

  console.log(`File: ${filePath}`);
  console.log(`Expected: ${expectedChecksum}`);
  console.log(`Actual:   ${actualChecksum}`);
  console.log(`Valid:    ${isValid}`);

  return isValid;
}

// Usage
async function main() {
  const bundleChecksum = await calculateChecksum('./my-app-1.2.3.zip');
  console.log('SHA256 Checksum:', bundleChecksum);
}

main();

체크섬의 중요성

배달完整성: 배달 중에 손상되지 않은 것을 확인합니다.
API 체크섬 검증: Capgo는 체크섬을 검증하기 전에 배달을 수락합니다.
플러그인 검증: 모바일 플러그인은 업데이트를 적용하기 전에 체크섬을 확인합니다.

최선의 방법

버ndल(버전) 관리: 사용 일관적인 의미 버전 일관되게
저장소 최적화: 사용하지 않는 버nd를 정기적으로 삭제합니다.
버nd(버전) 호환성: 적절한 최소 네이티브 버전 요구 사항을 설정합니다.
백업 전략: critical bundle (versions) 백업 유지

Endpoints

GET

https://api.capgo.app/bundle/

버전당 50개의 bundle 정보를 반환합니다.

Query Parameters

app_id: 앱 ID (필수)
page: 페이지 번호 (선택)

응답 유형

interface Bundle {
  app_id: string
  bucket_id: string | null
  checksum: string | null
  created_at: string | null
  deleted: boolean
  external_url: string | null
  id: number
  minUpdateVersion: string | null
  name: string
  native_packages: Json[] | null
  owner_org: string
  r2_path: string | null
  session_key: string | null
  storage_provider: string
  updated_at: string | null
  user_id: string | null
}

예제 요청

# Get all bundles
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/bundle/?app_id=app_123"

# Get next page
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/bundle/?app_id=app_123&page=1"

예제 응답

{
  "data": [
    {
      "id": 1,
      "app_id": "app_123",
      "name": "1.0.0",
      "checksum": "abc123...",
      "minUpdateVersion": "1.0.0",
      "storage_provider": "r2",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "deleted": false,
      "owner_org": "org_123",
      "user_id": "user_123"
    }
  ]
}

삭제

https://api.capgo.app/bundle/

앱에 대한 하나 이상의 패키지를 삭제합니다. 이 작업은 되돌릴 수 없으므로 주의가 필요합니다.

쿼리 매개변수

특정 번들 삭제를 위해:

interface BundleDelete {
  app_id: string
  version: string
}

모든 번들 삭제를 위해:

interface BundleDeleteAll {
  app_id: string
}

예제 요청

# Delete specific bundle
curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123",
    "version": "1.0.0"
  }' \
  https://api.capgo.app/bundle/

# Delete all bundles
curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123"
  }' \
  https://api.capgo.app/bundle/

성공 응답

{
  "status": "ok"
}

POST

https://api.capgo.app/bundle/

외부 URL을 가진 새로운 번들을 생성합니다.

Request Body

interface CreateBundleBody {
  app_id: string
  version: string
  external_url: string // Must be publicly accessible HTTPS URL
  checksum: string
}

예제 요청

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "version": "1.2.3",
    "external_url": "https://your-storage.com/bundles/app-1.2.3.zip",
    "checksum": "a1b2c3d4e5f6789abcdef123456789abcdef123456789abcdef123456789abcd"
  }' \
  https://api.capgo.app/bundle/

성공 응답

{
  "status": "ok"
}

POST (메타데이터)

https://api.capgo.app/bundle/metadata

링크 및 댓글 정보와 같은 번들 메타데이터를 업데이트합니다.

요청 본문

interface UpdateMetadataBody {
  app_id: string
  version_id: number // bundle (version) id
  link?: string
  comment?: string
}

예제 요청

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123",
    "version_id": 456,
    "link": "https://github.com/myorg/myapp/releases/tag/v1.0.0",
    "comment": "Fixed critical bug in authentication"
  }' \
  https://api.capgo.app/bundle/metadata

성공 응답

{
  "status": "success"
}

PUT

https://api.capgo.app/bundle/

특정 채널에 패키지를 설정합니다. 이 기능은 패키지(버전)를 배포에 사용하기 위해 채널과 연결합니다.

요청 본문

interface SetChannelBody {
  app_id: string
  version_id: number // bundle (version) id
  channel_id: number
  target?: "auto" | "stable" | "rollout" // default: auto
}

target progressive rollout이 설정된 채널에서 패키지를 연결하는 위치를 지정합니다:

auto progressive rollout이 설정된 경우 — rollout target; 그렇지 않은 경우 stable
rollout progressive rollout이 설정된 경우 항상 rollout target를 설정; stable fallback은 변경되지 않습니다.
stable progressive rollout이 설정된 경우 stable fallback을 대체합니다.

예시 요청

curl -X PUT \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_123",
    "version_id": 456,
    "channel_id": 789
  }' \
  https://api.capgo.app/bundle/

성공 응답

{
  "status": "success",
  "message": "Bundle 1.0.0 set to channel production"
}

오류 처리

일반 오류 상황 및 응답:

// Bundle not found
{
  "error": "Bundle not found",
  "status": "KO"
}

// Invalid bundle (version) format
{
  "error": "Invalid version format",
  "status": "KO"
}

// Storage error
{
  "error": "Failed to delete bundle from storage",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage bundles",
  "status": "KO"
}

일반적인 사용 사례

구성된 버전 삭제

// Delete outdated beta bundles (versions)
{
  "app_id": "app_123",
  "version": "1.0.0-beta.1"
}

앱 초기화

// Remove all bundles to start fresh
{
  "app_id": "app_123"
}

Storage Considerations

보존 정책: 오래된 번들을 얼마 동안 보관할 것인가를 정의합니다.
사이즈 관리: 번들의 크기와 저장 용량을 모니터링합니다.
백업 전략: critical bundle (version) 백업을 고려하세요.
비용 최적화: 불필요한 bundle을 제거하여 저장 비용을 최적화하세요.

Bundle에서 계속

Bundles를 사용하여 저장 공간 및 파일 처리를 계획하고 있습니다. Bundles storage 및 파일 처리를 계획하고 연결하려면 @capgo/capacitor-SQLite-저장소 @capgo/capacitor-data-storage-sqlite을 사용하여 native 데이터 저장소 기능을 사용하세요. Capgo 사용자 가이드 @capgo/capacitor-data-storage-sqlite native 기능을 위한 @capgo/capacitor-data-storage-sqlite @capgo/capacitor-파일 Capgo capgo/capacitor-파일 의 구현 세부 사항 Capgo capgo/capacitor-파일 사용 Capgo capgo/capacitor-파일을 사용하여 Native 기능 @capgo/capacitor-업로더 Capgo capgo/capacitor-업로더의 구현 세부 사항

번들

번들 이해

수동으로 번들 만들기 (Without CLI)

: 수동으로 번들을 만들고 업로드하는 방법에 대한 설명입니다. (Without __CAPGO_KEEP_0__ __CAPGO_KEEP_1__: )

Step 2: Capgo CLI와 동일한 패키지를 사용하여 번들 ZIP을 생성하세요

필요한 패키지를 설치하세요

자바스크립트와 함께 ZIP 파일을 생성하세요 (Capgo와 CLI와 동일)

3단계: CLI와 동일한 패키지를 사용하여 SHA256 체크섬 계산

4단계: 저장소에 ZIP 파일 업로드

5단계: Capgo API에 Capgo API 등록

API 매개변수

패키지 구조 요구 사항

유효한 번들 구조

완전한 수동 워크플로 예제

체크섬 검증

자바스크립트 체크섬 계산 (Capgo CLI과 동일)

체크섬의 중요성

최선의 방법

Endpoints

GET

Query Parameters

응답 유형

예제 요청

예제 응답

삭제

쿼리 매개변수

예제 요청

성공 응답

POST

Request Body

예제 요청

성공 응답

POST (메타데이터)

요청 본문

예제 요청

성공 응답

PUT

요청 본문

예시 요청

성공 응답

오류 처리

일반적인 사용 사례

Storage Considerations

Bundle에서 계속

: 수동으로 번들을 만들고 업로드하는 방법에 대한 설명입니다. (Without __CAPGO_KEEP_0 CAPGO_KEEP_1__: )