__CAPGO_KEEP_1__

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

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

번들 이해

번들은 앱의 웹 콘텐츠의 특정 버전을 나타내며 다음을 포함합니다:

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

수동 번들 생성 (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 내부에서 사용하는 정확한 자바스크립트 패키지를 사용하여 호환성을 보장합니다.

필요한 패키지 설치

npm install adm-zip @tomasklaen/checksum

자바스크립트 ( Capgo CLI와 동일한)로 ZIP 번들 만들기

참고: 아래 예시에서 version API이란 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 파일을 웹에 접근 가능한 저장소에 업로드하세요:

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

중요: 번들은 공개적으로 접근 가능해야 합니다 via HTTPS URL (no authentication required). Capgo’s servers need to download the bundle from this URL.

Examples of valid public URLs:

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에 등록하세요.

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`	앱 식별자	Yes
`version`	버전(버전) Semantic 버전 (예를 들어, “1.2.3”)	Yes
`external_url`	공개적으로 접근 가능 HTTPS URL에서 버전이 다운로드 될 수 있는 URL(인증이 필요하지 않음)	Yes
`checksum`	SHA256 체크섬 (zip 파일)	Yes

버전 구조 요구 사항

__CAPGO_KEEP_0__이 포함된 압축 파일은 다음 요구 사항을 충족해야 합니다.

Root Index File: __CAPGO_KEEP_0__이 포함되어 있어야 합니다. index.html __CAPGO_KEEP_0__ Integration
: Capacitor을 호출해야 합니다.Asset Paths notifyAppReady() in your app code
Valid Bundle Structure__CAPGO_KEEP_0__이 포함된 압축 파일의 구조는 다음과 같습니다.

Copy to clipboard

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

체크섬 검증

JavaScript 체크섬 계산 (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는 체크섬을 확인한 후 배포물을 수락합니다.
플러그인 확인: 모바일 플러그인이 업데이트를 적용하기 전에 체크섬을 확인합니다.

최적화 방법

배포물(버전) 관리: 사용하세요 버전 관리를 일관되게 사용하세요 저장소 최적화
: 사용하지 않는 번들을 정기적으로 삭제하세요버전 호환성 (번들)
: 적절한 최소 네이티브 버전 요구 사항을 설정하세요백업 전략
: 중요한 번들의 백업을 유지하세요엔드포인트

엔드포인트 섹션

__CAPGO_KEEP_0__

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

배포 정보를 가져옵니다. 1페이지당 50개의 배포를 반환합니다.

Query Parameters

app_id: 앱 ID가 필요합니다.
page: 페이지 번호를 지정할 수 있습니다.

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"

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

__CAPGO_KEEP_3__

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

__CAPGO_KEEP_4__

__CAPGO_KEEP_5__

__CAPGO_KEEP_7__

interface BundleDelete {
  app_id: string
  version: string
}

__CAPGO_KEEP_9__

interface BundleDeleteAll {
  app_id: string
}

__CAPGO_KEEP_1__

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

__CAPGO_KEEP_4__

{
  "status": "ok"
}

__CAPGO_KEEP_5__

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

__CAPGO_KEEP_7__

__CAPGO_KEEP_8__

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 (Metadata)

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

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

__CAPGO_KEEP_0__

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

__CAPGO_KEEP_3__

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

__CAPGO_KEEP_7__

{
  "status": "success"
}

__CAPGO_KEEP_10__

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

__CAPGO_KEEP_0__을 특정 채널에 설정합니다. 이 링크는 버전을 배포에 사용하는 채널과 버전을 연결합니다.

__CAPGO_KEEP_0__

interface SetChannelBody {
  app_id: string
  version_id: number // bundle (version) id
  channel_id: number
}

__CAPGO_KEEP_3__

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/

__CAPGO_KEEP_7__

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

__CAPGO_KEEP_10__

일반적인 오류 상황 및 응답:

// 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/capacitor-data-storage-sqlite capgo/capacitor 데이터 저장소 SQLite에 대한 implementation detail Using capgo/capacitor-data-storage-sqlite capgo/capacitor-data-storage-sqlite의 native capability에 대해 @capgo/capacitor-file capgo/capacitor 파일에 대한 implementation detail Using capgo/capacitor-file capgo/capacitor-file의 native capability에 대해 capgo/capacitor-uploader capgo/capacitor-uploader에 대한 implementation detail