Bundle

__CAPGO_KEEP_0__의 업데이트 패키지 core를 구성하는 Bundles입니다. 각 Bundles에는 앱의 콘텐츠를 구성하는 웹 자산 (HTML, CSS, JS) 이 포함되어 있습니다. Bundles __CAPGO_KEEP_1__는 이러한 업데이트 패키지를 관리하는 데 사용되며, 목록 및 삭제를 포함합니다.

Bundles are the core update packages in Capgo. Each bundle contains the web assets (HTML, CSS, JS) that make up your app’s content. The Bundles API allows you to manage these update packages, including listing and deleting them.

__CAPGO_KEEP_0__

Bundle은 앱의 웹 콘텐츠의 특정 버전 (version) 을 나타내며 다음을 포함합니다:

Bundle (version): Semantic 버전 번호 Bundle의 버전
Checksum: Bundle의 무결성을 확인하기 위한 고유한 해시
Storage Info: Bundle이 저장되는 위치와 방법에 대한 세부 정보
Native Requirements: Native 앱의 최소 버전 요구 사항
Metadata: 생성 시간, 소유권 및 기타 추적 정보

수동 번들 생성 (Without CLI)

다음과 같이 Capgo CLI 없이 수동으로 번들을 생성하고 업로드하는 방법입니다:

1단계: 앱 빌드

먼저 앱의 웹 자산을 빌드하세요:

npm run build

2단계: Capgo CLI와 동일한 패키지를 사용하여 번들 ZIP 생성

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

필요한 패키지 설치

npm install adm-zip @tomasklaen/checksum

Capgo CLI와 동일한 자바스크립트를 사용하여 ZIP 파일을 생성하세요.

아래 예시에서 __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단계: __CAPGO_KEEP_0__에 번들 업로드

__CAPGO_KEEP_0__에 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__의 서버가 다운로드할 수 있는 공개 URL이어야 합니다. via HTTPS URL (no authentication required). Capgo’s servers need to download the bundle from this URL.

5단계: __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

Capgo : API

Capgo 외부 패키지를 직접 API 호출을 사용하여 Capgo에 등록하세요.

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`	패키지 (버전) 세미나 버전 예시: “1.2.3”)	네
`external_url`	공개적으로 접근 가능 다운로드할 수 있는 HTTPS URL (인증 필요 없음)	네
`checksum`	zip 파일의 SHA256 체크섬	네

배포 구조 요구 사항

당신의 배포 zip은 다음 요구 사항을 따라야 합니다:

루트 인덱스 파일: 반드시 index.html 기본 경로에 위치
Capacitor 통합: 호출해야 함 notifyAppReady() 앱에 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();

체크섬 중요성

Bundle의 무결성: 전송 중에 Bundle이 손상되지 않았는지 확인합니다
API 검증: Capgo는 체크섬을 검증하기 전에 Bundle을 수락합니다
플러그인 검증: 모바일 플러그인은 업데이트를 적용하기 전에 체크섬을 검증합니다

최선의 방법

Bundle (버전) 관리: 버전 일관되게 사용하십시오
저장소 최적화: 사용하지 않는 번들을 정기적으로 제거하십시오
번들(버전) 호환성: 적절한 최소 원시 버전 요구 사항을 설정하십시오
백업 전략: 중요한 번들의 백업을 유지하십시오

엔드포인트

GET

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

번들을 검색하여 정보를 반환합니다. 1페이지당 50개의 번들을 반환합니다.

쿼리 매개변수

app_id: Required. 앱의 ID
page: Optional. 페이징을 위한 페이지 번호

Response Type

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
}

Terminal window

# 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"

Example Request

{
  "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을 가진 새로운 번들을 생성하세요.

요청 본문

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 채널에서 배포할 때의 Bundle 위치를 지정합니다.

auto — 진행 중인 롤아웃이 구성된 경우 롤아웃 대상; 안정적일 경우 (기본값).
rollout — 항상 롤아웃 대상 설정; 안정적 기본값은 변경되지 않음.
stable — 안정적 기본값 대체 (이스케이프 하치).

예제 요청

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"
}

저장소 고려 사항

보관 정책: 오래된 번들 보관 기간 정의
크기 관리: 번들 크기 및 저장소 사용량 모니터링
백업 전략: 중요 번들(버전) 백업 고려
비용 최적화: 불필요한 번들을 삭제하여 저장소 비용 최적화

번들에서 계속

만약에 사용 중인 경우 번들 저장 및 파일 처리를 계획하고 연결하세요. @capgo/capacitor-data-storage-sqlite implementation detail에 대한 @capgo/capacitor-data-storage-sqlite implementation detail을 사용하여 @capgo/capacitor-data-storage-sqlite native capability을 사용하여 @capgo/capacitor-data-storage-sqlite @capgo/capacitor-file implementation detail에 대한 @capgo/capacitor-file implementation detail을 사용하여 @capgo/capacitor-file native capability을 사용하여 @capgo/capacitor-file implementation detail을 사용하여 @capgo/capacitor-uploader implementation detail에 대한 @capgo/capacitor-uploader