Bundle

__CAPGO_KEEP_0__의 업데이트 패키지 core를 구성하는 Bundles의 설정 지시를 복사하세요.

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은 앱의 웹 콘텐츠의 특정 버전을 나타내며 다음을 포함합니다:

Bundle (버전): Semantic 버전 번호 Bundle의 버전
체크섬: Bundle의 무결성을 확인하기 위한 고유한 해시
저장 정보: Bundle이 저장되는 위치와 방법에 대한 세부 정보
네이티브 요구 사항: Native 앱의 최소 버전 요구 사항
메타 데이터: __CAPGO_KEEP_0__

수동 번들 생성 (CLI 없이)

Here’s how to create and upload bundles manually without using the Capgo CLI:

1단계: 앱 빌드

앱의 웹 자산을 빌드하세요.

npm run build

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

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

필요한 패키지 설치

npm install adm-zip @tomasklaen/checksum

Capgo CLI와 동일한 JavaScript를 사용하여 ZIP 배포본을 생성하세요.

아래 예제에서 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();

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"

중요중요 4단계: __CAPGO_KEEP_0__에 번들 업로드 HTTPS URL을 통해 공개적으로 접근할 수 있어야 합니다. Capgo 서버는 이 URL에서 번들을 다운로드해야 합니다.

유효한 공개 URL 예시:

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 호출을 사용하여 외부 번들 등록

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 version 예시: “1.2.3”)	Yes
`external_url`	공개적으로 접근할 수 있음 다운로드할 수 있는 HTTPS URL (인증이 필요하지 않음)	Yes
`checksum`	zip 파일의 SHA256 체크섬	Yes

배포 구조 요구 사항

배포할 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 Integrity: 전송 중에 패키지가 손상되지 않았는지 확인합니다
API Verification: Capgo는 체크섬을 검증하기 전에 패키지를 수락합니다
Plugin Verification: 모바일 플러그인은 업데이트를 적용하기 전에 체크섬을 검증합니다

Best Practices

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

엔드포인트

GET

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

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

쿼리 매개변수

app_id: 필수. 앱의 ID
page: Optional. 페이지 번호 (pagination)

응답 유형

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

요청 본문

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
}

예제 요청

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_KEEP_0__/__CAPGO_KEEP_1__-data-storage-sqlite와 연결하세요 상세 구현을 위해 @capgo/capacitor-data-storage-sqlite 참조하세요 버스를 @capgo/capacitor-data-storage-sqlite 사용하세요 @capgo/capacitor-data-storage-sqlite Capgo의 내장 기능을 사용하는 @capgo/capacitor-data-storage-sqlite 에 대해 @capgo/capacitor-file Capgo의 구현 세부 정보를 사용하는 @capgo/capacitor-file 에 대해 Capgo의 @capgo/capacitor-file을 사용하는 Capgo의 내장 기능을 사용하는 @capgo/capacitor-file, 그리고 @capgo/capacitor-uploader Capgo의 구현 세부 정보를 사용하는 @capgo/capacitor-uploader 에 대해