Bundle

설치 단계 및 이 플러그인의 전체 마크다운 가이드를 포함한 설정 명령어를 복사하세요.

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의 버전
Checksum: Bundle의 무결성을 확인하는 고유한 해시
Storage Info: Bundle이 저장되는 위치와 방법에 대한 세부 정보
Native Requirements: Native 앱의 최소 버전 요구 사항
Metadata: 생성 시간, 소유권 및 기타 추적 정보

수동 번들 생성 (Without CLI)

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

1단계: 앱 빌드

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

npm run build

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

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

필요한 패키지 설치

npm install adm-zip @tomasklaen/checksum

Capgo CLI와 동일한 JavaScript를 사용하여 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"

중요4단계: __CAPGO_KEEP_0__에 번들 업로드 번들이 __CAPGO_KEEP_0__의 서버에서 다운로드될 수 있도록 Capgo의 번들이 공개적으로

HTTPS 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

Step 5: Register Bundle with 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`	버전 세마틱 버전 예시: “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 Integrity: 전송 중에 패키지가 손상되지 않았는지 확인합니다.
API Verification: Capgo는 패키지의 체크섬을 검증하기 전에 패키지를 수락합니다.
Plugin Verification: 모바일 플러그인은 업데이트를 적용하기 전에 체크섬을 검증합니다.

Best Practices

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

엔드포인트

GET

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

번들을 검색하여 정보를 반환합니다. 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
}

예제 요청

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

DELETE

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 for the native capability in Using @capgo/capacitor-data-storage-sqlite, @capgo/capacitor-file for the implementation detail in @capgo/capacitor-file, Using @capgo/capacitor-file for the native capability in Using @capgo/capacitor-file, and @capgo/capacitor-uploader for the implementation detail in @capgo/capacitor-uploader.