# SDK APIリファレンス

SDKの初期化設定、Hooks、更新チェックとダウンロードの結果、エラーの扱いを確認できます。

まず [最小限の統合](/docs/integration) を完了してください。このページを使用してオプションを検索します。すべてのオプションが必要なわけではありません。レポートと構成に 1 つのクライアント インスタンスを再利用します。

## 概要 {#overview}

Pakta SDK (npm パッケージ `rn-update`) のすべてのパブリック API は、パッケージ エントリからエクスポートされます。 5つのグループ:

- `Pakta` クライアント クラスと `ClientOptions`
- `UpdateProvider` (別名 `PaktaProvider`) React 統合
- `useUpdate()` / `useUpdateProgress()` / `usePakta()` フック
- メタデータとクラッシュレポートの相関関係を更新します
・`UpdateError`タイプとイベントモデル

## クライアントクラス {#client}

```tsx
import { Pakta } from 'rn-update';

const client = new Pakta({
  appKey: '<your appKey>',
  updateStrategy: 'silentAndLater',
});

// Update configuration at runtime (idempotent merge; re-renders the Provider)
client.setOptions({ checkStrategy: 'onAppResume' });

// Manually report a JS exception (global ErrorUtils is chained automatically)
client.captureException(error, { context: 'checkout' });
```

## クライアントオプション {#client-options}

|フィールド |タイプ |デフォルト |説明 |
| --- | --- | --- | --- |
| `appKey` | `string` |必須 |コンソールによって割り当てられたプラットフォーム appKey |
| `server` | `{ main: string[]; queryUrls?: string[] }` |公式エンドポイント |セルフホステッド サービスのアドレスとエンドポイント検出リスト |
| `updateStrategy` |以下を参照 | `'alertUpdateAndIgnoreError'` |プロンプトとアクティベーション戦略 |
| `checkStrategy` | `'onAppStart' \| 'onAppResume' \| 'both' \| null` | `'both'` |タイミングを確認してください。 `null` は JS 自動チェックを無効にします |
| `autoMarkSuccess` | `boolean` | `true` |実行中のバージョンが正常であることを自動確認する |
| `autoMarkSuccessDelayMs` | `number` | `1000` |自動確認遅延。重要なモジュールの読み込みが遅い場合に発生します。
| `healthCheck` | `() => boolean \| Promise<boolean>` | — |確認前のヘルスゲート。 `false` はこの起動をスキップします |
| `maxRetries` | `number` | `3` |ダウンロード再試行回数 |
| `logger` | `({ type, data }) => void` | — |イベントロガーを更新する |
| `locale` | `'zh' \| 'en'` | `'zh'` |組み込みのプロンプト言語 |
| `debug` | `boolean` | `false` |詳細な内部ログ |
| `throwError` | `boolean` | `false` | JS に更新エラーをスローする |
| `testChannel` | `boolean` | `true` | QR コード/ディープ リンクのテストを尊重します。実稼働環境で `false` を使用する |
| `beforeCheckUpdate` / `afterCheckUpdate` |フック | — |チェックごとに |
| `beforeDownloadUpdate` / `afterDownloadUpdate` |フック | — |ダウンロードごと |
| `beforeReload` | `(ctx: { type: 'switchVersion' \| 'restartApp' }) => …` | — |リロード前 |
| `onPackageExpired` |フック | — |期限切れパッケージのデフォルト動作をオーバーライドします。
| `disableTelemetry` | `boolean` | `false` |クライアント テレメトリと JS エラー トランスポートを無効にする |
| `disableErrorReporting` | `boolean` | `false` | JS エラー報告のみを無効にする |

`updateStrategy` 値: `'silentAndNow'`、`'silentAndLater'`、`'alertUpdateAndIgnoreError'`、`'alwaysAlert'`。

## React 統合 {#react}

```tsx
import { Pakta, UpdateProvider, PaktaProvider, useUpdate, usePakta, useUpdateProgress } from 'rn-update';
```

- `UpdateProvider` / `PaktaProvider` (エイリアス) — `client` プロップを受け取ります。同じプロセスに 2 番目のプロバイダーをマウントするとスローされます。
- `useUpdate()` — 状態とアクションを更新します (下記)。
- `useUpdateProgress()` — 分離されたダウンロード進行状況 `{ hash, received, total, progress? }`。
- `usePakta()` — `useUpdate()` のエイリアスで、同じ状態とアクションを返します。 `useUpdate().client` を通じてインスタンスにアクセスします。

`useUpdate()` によって返された `UpdateContextValue`:

|メンバー |説明 |
| --- | --- |
| `updateInfo` |最終 `CheckResult` |
| `lastError` |最後のエラー |
| `currentHash` / `packageVersion` |アクティブな更新ハッシュとネイティブ パッケージのバージョン |
| `currentVersionInfo` | `{ name?, description?, metaInfo? }` |
| `checkUpdate(params?)` |手動チェック |
| `downloadUpdate(info?)` |ダウンロード |
| `switchVersion(info?)` |今すぐダウンロード バージョンに切り替えます (JS のリロード) |
| `switchVersionLater(info?)` |次回の起動時に適用 |
| `markSuccess()` |現在のバージョンが正常であることを確認します |
| `restartApp()` |アプリを再起動します |
| `resetToPackagedBundle(options?)` |バンドルされた JS に戻る |
| `downloadAndInstallApk(url)` |ネイティブ アップグレード APK (期限切れのパッケージ) をダウンロードしてインストールします。
| `parseTestQrCode(code)` |テスト QR コード / ディープ リンクを解析する |
| `dismissError()` |クリア

## CheckResult とバージョン情報 {#check-result}

```ts
interface CheckResult {
  upToDate?: boolean;      // already latest
  update?: boolean;        // update available
  expired?: boolean;       // native package expired; downloadUrl points to the new binary
  paused?: 'app' | 'package'; // application or native package paused
  downloadUrl?: string;    // expired-binary download address
  bundleStatus?: 'matched' | 'rebuiltSameJs' | 'unknownBundle';
  name?: string;           // version name
  hash?: string;           // version hash
  description?: string;    // version description
  metaInfo?: string;       // custom metadata (JSON string)
  config?: { rollout?: Record<string, number>; forceBoot?: boolean };
  pdiff?: string;          // precise differential package
  diff?: string;           // generic differential package
  full?: string;           // full package
}
```

`bundleStatus` はネイティブ登録を反映します: `matched` — 完全一致。 `rebuiltSameJs` — 同じ JS フィンガープリントですが、ビルド時間が異なります (フルパッケージのみ)。 `unknownBundle` — 未登録のフィンガープリント (厳密なチャネル配信の下で現在のバージョンに保持されます)。

## メタデータとクラッシュ相関関係 {#metadata}

```tsx
import * as Sentry from '@sentry/react-native';
import { attachToSentry, getUpdateMetadata } from 'rn-update';

// Call after your existing Sentry initialization.
attachToSentry(Sentry);
const metadata = getUpdateMetadata();
```

`getUpdateMetadata()` は、現在の更新 ID (`currentVersion` を含む) を返します。 `updateMetadataTags()` は、Sentry タグに対応するキーと値のペアを構築します。

## エラーとイベント {#errors}

- `UpdateError` は、安定した機械読み取り可能な `code` (`UpdateErrorCode`) を搭載しています。
- `EventData` (`logger` コールバック) には、エラーの詳細を含む `type` (`checking`、`downloading`、`downloadSuccess`、`rollback`、`markSuccess`、`errorUpdate` など) が含まれます。
- JavaScriptエラーの報告とスタックトレースの復元については、[エラー診断](/docs/errors)を参照してください。

setAttribute/setAttributes を使用して初期化されたレポーターを `attachToCrashlytics(reporter)` に渡します。デフォルトのタグ接頭辞は `pakta.` で、実行中の更新タグは `pakta.currentVersion` です。

|追加オプション |デフォルト |目的 |
| --- | --- | --- |
| `disableNativeCheck` |偽 |ネイティブ起動チェックを無効にする |
| `dismissErrorAfter` |設定を解除する |この数ミリ秒後に lastError をクリアします。
| `overridePackageVersion` |ネイティブバージョン |診断 JS リクエストのオーバーライド。インストーラーは変更されません。

運用環境のデフォルトはalertUpdateAndIgnoreErrorです。開発のデフォルトは alwaysAlert です。デバッグでは、実際のアクティベーションではなく、開発中のチェック/ダウンロードが可能になります。 updateStrategy は null も受け入れますが、プロバイダーを手動で呼び出すとプロンプトが表示されることがあります。完全にカスタム UI の場合は、以下のインスタンス メソッドを使用します。

## checkUpdate(パラメータ?) {#async-function-checkupdate}

UpdateProvider の子孫内で呼び出します。引数を指定しないと、このデバイスのアップデートを確認し、updateInfo を保存し、設定されたプロンプト/ダウンロード戦略を実行します。 extra.toHash はテスト用のアップデートを選択します。ネイティブ チャネルは設定されません。スキップされた場合は CheckResult または unknown を返します。失敗はデフォルトで lastError に送られるか、throwError が有効になっている場合は throw されます。生の結果と独自の UI については、マニュアルの例に示されているように client.checkUpdate() を使用します。

```typescript
checkUpdate(params?: { extra?: { toHash?: string } }): Promise<CheckResult | undefined>
```

```tsx
const { checkUpdate, lastError } = useUpdate();

async function onCheck() {
  const info = await checkUpdate();
  if (!info) return;
  if (info.expired) {
    return;
  }
  if (info.paused) return;
  if (info.upToDate) return;
  if (info.update) {
  }
}
```


## ダウンロードアップデート(情報?) {#async-function-downloadupdate}

infoを省略した場合は最新のチェック結果を使用します。プロバイダーのダウンロード フローの後に true を返します。 false は、ファイルが既にダウンロードされている場合でも、使用可能なアップデートがない場合、または afterDownloadUpdate が拒否権を持っています。また、アクティベーション戦略も実行します。silentAndNow はリロードを要求し、silentAndLater はアクティベーションをスケジュールします。その他の値はプロンプトを表示できます。ダウンロードのみの場合、 client.downloadUpdate(info, onProgress?) はハッシュまたは未定義を返します。クライアント切り替えメソッドはそのハッシュを受け入れます。

```typescript
downloadUpdate(info?: CheckResult): Promise<boolean | undefined>
```

```tsx
const { updateInfo, downloadUpdate } = useUpdate();

async function onDownload() {
  if (!updateInfo?.update) return;
  const completed = await downloadUpdate(updateInfo);
  if (!completed) return;
}
```


## downloadAndInstallApk(url) {#async-function-downloadandinstallapkurl}

完全な Android APK をダウンロードし、システム インストーラーを開きます。 URL は HTTPS を使用し、AAB、ppk、またはストア ページではなく、APK を指す必要があります。 Android 以外のプラットフォームでは、この操作をスキップします。 APK は、インストールされているアプリケーション ID および署名 ID と一致し、システム バージョン要件を満たす必要があります。 Promise<void> が完了しても、ユーザーがアプリをインストールしたことは証明されません。デフォルトのエラーは lastError に表示されます。 try/catch の throwError を有効にします。

REQUEST_INSTALL_PACKAGES をマニフェスト内、アプリケーション外に追加し、ネイティブ インストーラーを再構築します。 SDK は Android インストール セッションを使用します。この API には FileProvider を追加しないでください。プレーンな HTTP URL は拒否されます。以下のボタンの例は UpdateProvider の下に属し、実際の APK URL (オプションで CheckResult.downloadUrl から) を受け取ります。

Android 8 以降では、ユーザーはこのアプリに不明なアプリのインストールを許可する必要があります。 SDK は可能な場合は設定を開き、APK_INSTALL_PERMISSION_REQUIRED を報告します。許可後、戻って再度ボタンを押してください。同時ダウンロードはスキップされます。 APK_INSTALL_PENDING は、ダウンロードされた APK がインストールを待機していることを意味します。ダウンロードをループさせないでください。インストールが失敗した場合は、APK、パッケージ ID、署名、バージョンを確認してください。配布にストアのアップグレードが必要な場合は、代わりにアプリのストア リンクを使用してください。

```typescript
downloadAndInstallApk(url: string): Promise<void>
```

```xml title="android/app/src/main/AndroidManifest.xml"
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
```

```tsx title="NativeUpgradeButton.tsx"
import { useState } from 'react';
import { Button, Platform, Text, View } from 'react-native';
import { useUpdate, useUpdateProgress } from 'rn-update';

export function NativeUpgradeButton({ apkUrl }: { apkUrl: string }) {
  const { downloadAndInstallApk, lastError } = useUpdate();
  const progress = useUpdateProgress();
  const [busy, setBusy] = useState(false);
  const [error, setError] = useState('');

  async function install() {
    if (busy || !apkUrl) return;
    setBusy(true);
    setError('');
    try {
      await downloadAndInstallApk(apkUrl);
    } catch (cause) {
      setError(cause instanceof Error ? cause.message : String(cause));
    } finally {
      setBusy(false);
    }
  }

  if (Platform.OS !== 'android') return null;
  const percent = progress?.hash === 'downloadingApk' && progress.total > 0
    ? Math.round(progress.received / progress.total * 100)
    : undefined;
  return (
    <View>
      <Button title={busy ? 'Downloading' : 'Upgrade app'}
        disabled={busy || !apkUrl} onPress={() => { void install(); }} />
      {percent !== undefined ? <Text>{percent}%</Text> : null}
      {error || lastError ? <Text>{error || lastError?.message}</Text> : null}
    </View>
  );
}
```


## マーク成功() {#function-marksuccess}

実行中のアップデートが使用可能であることを確認します。ネイティブ コードが受け入れられる場合は true、拒否される場合は false、または開発中または最初の更新リリース以外ですでにマークされている場合は未定義を返します。ネイティブの失敗がスローされます。プロバイダーは通常、約 1000 ミリ秒後に確認します。後期初期化の場合は autoMarkSuccess:false を設定し、重要な初期化が成功した後に呼び出します。ダウンロード直後に成功をマークしないでください。確認後に発生したエラーが必ずしもロールバックをトリガーするとは限りません。

```typescript
markSuccess(): Promise<boolean | undefined>
```

```tsx title="Existing client options"
autoMarkSuccess: false,
```

```tsx title="After critical initialization"
const { markSuccess } = useUpdate();

async function confirmReady() {
  try {
    const accepted = await markSuccess();
    if (accepted === false) {
    }
  } catch (error) {
  }
}
```


## currentVersionInfo {#currentversioninfo}

実行中の更新の名前、説明、JSON 文字列メタ情報、または null が含まれます。 updateInfo は、現在実行中の更新ではなく、最新のチェックからの候補を説明します。 currentHash は、埋め込みバンドルの場合は空です。 packageVersion はネイティブ インストーラーのバージョンであり、更新名によって変更されません。

```typescript
currentVersionInfo: {
  name?: string;
  description?: string;
  metaInfo?: string;
} | null
```

```tsx
const { currentVersionInfo, currentHash, packageVersion } = useUpdate();
const label = currentVersionInfo?.name || 'Embedded version';
```


## getCurrentVersionInfo() {#async-function-getcurrentversioninfo}

名前、説明、メタ情報の Promise を返す互換性メソッド。新しいコードは currentVersionInfo を直接読み取る必要があります。

```typescript
getCurrentVersionInfo(): Promise<{
  name?: string;
  description?: string;
  metaInfo?: string;
}>
```

```tsx
const { getCurrentVersionInfo } = useUpdate();
const version = await getCurrentVersionInfo();
```


## restartApp() {#function-restartapp}

React Native 環境のネイティブ再起動を要求します。アップデートのチェックやダウンロードは行わず、OS レベルのプロセスの強制終了も保証しません。まず保留中の作業を保存します。 beforeReload は型 restartApp を受け取ります。 false はキャンセルします。フックおよびネイティブの再起動エラーは拒否されるため、ボタン ハンドラーで捕捉される必要があります。

```typescript
restartApp(): Promise<void>
```

```tsx
const { restartApp } = useUpdate();
await restartApp();
```


## resetToPackagedBundle(options?) {#async-function-resettopackagedbundleoptions}

ダウンロードされたアップデートとローカルアップデートの状態を削除し、デバイス ID を保持します。任意の履歴アップデートではなく、インストーラーに埋め込まれたバンドルを復元します。デフォルトでは、アクティベーションは次の起動まで待機します。 restart:true はさらに再起動を要求します。真の結果は、リセットが証明され、再起動が成功したわけではありません。フックが拒否するか、再起動が失敗する可能性があります。 Web は false を返します。サポートされていないネイティブ ビルドは RESET_FAILED を報告します。結果を確認してください。最初に障害のあるサーバーのリリースを停止するか、後でチェックして再度ダウンロードすることができます。 [ストップリリース](/docs/console#stop)を参照してください。

```typescript
resetToPackagedBundle(options?: { restart?: boolean }): Promise<boolean | undefined>
```

```tsx
const { resetToPackagedBundle } = useUpdate();
const reset = await resetToPackagedBundle({ restart: true });
if (!reset) {
}
```


## switchVersion(情報?) {#function-switchversion}

すでにダウンロードされているアップデートにすぐに切り替わります。デフォルトは最新の CheckResult で、ハッシュが存在しない場合はスキップし、次回の起動が正常であることが証明された場合ではなく、ネイティブ リロードが要求された場合に true を解決します。まずはダウンロードしてください。 beforeReload は false でキャンセルできます。クライアント インスタンスに相当するものは、文字列 client.switchVersion(hash) を受け入れます。

```typescript
switchVersion(info?: CheckResult): Promise<boolean | undefined>
```

```tsx
const { switchVersion, updateInfo } = useUpdate();
if (updateInfo?.hash) await switchVersion(updateInfo);
```


## switchVersionLater(情報?) {#function-switchversionlater}

現在の画面を保持したまま、次回の起動時にダウンロード済みのアップデートをスケジュールします。デフォルトは最新の結果です。欠落しているハッシュはスキップされます。 Promise<void> を返し、beforeReload を呼び出しません。完全に閉じてから再度テストしてください。クライアント インスタンスに相当するものは client.switchVersionLater(hash) です。

```typescript
switchVersionLater(info?: CheckResult): Promise<void>
```

```tsx
const { switchVersionLater, updateInfo } = useUpdate();
if (updateInfo?.hash) await switchVersionLater(updateInfo);
```


## parseTestQrCode(コード) {#function-parsetestqrcodeqrcode-string}

スキャンされた JSON 文字列または UpdateTestPayload オブジェクトを受け入れます。 true の結果は、テスト ペイロードが認識されたことを意味するだけで、ダウンロードやアクティベーションが成功したことを意味するものではありません。タイプを __rnPaktaVersionHash に設定し、データを完全な更新ハッシュに設定します。 testChannel:false はペイロードのテストを拒否します。独自のスキャナ UI を提供します。既存のアプリのディープ リンクの場合は、 ?type=__rnPaktaVersionHash&data=HASH; を追加します。ネイティブ スキームはすでに構成され、再構築されている必要があります。これは、インストーラーの固定配布チャネルとは異なります。

```typescript
parseTestQrCode(code: string | UpdateTestPayload): boolean
```

```tsx
const { parseTestQrCode } = useUpdate();
const accepted = parseTestQrCode({
  type: '__rnPaktaVersionHash',
  data: 'REPLACE_WITH_FULL_UPDATE_HASH',
});
```


## useUpdateProgress() {#use-update-progress}

ProgressData または未定義を返します。受信したバイト数と合計バイト数。 progress は 0 ～ 100 のオプションのパーセンテージです。APK progress はバイト数のみを提供する場合があります。合計が不明な場合は不確定な状態を表示します。このフックは進行状況のみのコンポーネントに使用します。

```tsx
import { Text } from 'react-native';
import { useUpdateProgress } from 'rn-update';

export function DownloadProgress() {
  const data = useUpdateProgress();
  if (!data) return null;
  const percent = data.progress ?? (data.total > 0
    ? Math.round(data.received / data.total * 100) : undefined);
  return <Text>{percent === undefined ? 'Downloading' : `${percent}%`}</Text>;
}
```


## dismissError() {#dismiss-error}

ダウンロードしたコンテンツを再試行したり変更したりせずに、lastError をクリアします。エラー UI を閉じるときに呼び出します。クライアント オプションの dismissErrorAfter:5000 を指定すると、5 秒後にクリアされます。

```tsx
const { lastError, dismissError } = useUpdate();
```


## カスタム更新 UI を構築する {#custom-update}

UI が完全なフローを所有する場合は、インスタンス メソッドを使用します。 client.downloadUpdate はハッシュを返し、クライアント切り替えメソッドはハッシュを受け入れます。これらはフックメソッドとは異なります。 checkStrategy:null と throwError:true を既存のクライアントに追加します。ネイティブのバックグラウンド チェックは別のものです。 disableNativeCheck:true はそれらを無効にし、その回復パスを放棄します。この例では、ダウンロードして次回起動のアクティベーションをスケジュールし、進行状況とエラーを報告します。

```tsx title="ManualUpdateButton.tsx"
import { useState } from 'react';
import { Button, Text, View } from 'react-native';
import { useUpdate } from 'rn-update';

export function ManualUpdateButton() {
  const { client } = useUpdate();
  const [busy, setBusy] = useState(false);
  const [message, setMessage] = useState('');
  async function update() {
    if (!client || busy) return;
    setBusy(true);
    try {
      const info = await client.checkUpdate();
      if (!info?.update) {
        setMessage(info?.expired ? '请Upgrade app' : 'No available update');
        return;
      }
      const hash = await client.downloadUpdate(info, (data) => {
        setMessage(data.progress === undefined ? 'Downloading' : `${data.progress}%`);
      });
      if (!hash) return;
      await client.switchVersionLater(hash);
      setMessage('Downloaded; applies on next launch');
    } catch (error) {
      setMessage(error instanceof Error ? error.message : String(error));
    } finally {
      setBusy(false);
    }
  }
  return <View>
    <Button title="Check and download" disabled={busy} onPress={() => { void update(); }} />
    <Text>{message}</Text>
  </View>;
}
```


## フックの確認、ダウンロード、リロード {#lifecycle-hooks}

既存のクライアントにフックを追加します。 beforeCheckUpdate が false を返すと、チェックがスキップされます。 afterCheckUpdate は完了/スキップ/エラーと結果またはエラーを受け取り、結果は置き換えられません。 beforeDownloadUpdate が false を返すと、ダウンロードがスキップされます。 afterDownloadUpdate が false を返すと、プロバイダーのダウンロード後のアクションが停止します。 onPackageExpired が false を返すと、組み込みのインストーラーのアップグレード処理が妨げられます。 beforeReload はタイプ switchVersion/restartApp とオプションのハッシュを受け取ります。 false またはスローされたエラーによりリロードできません。

The example calls your own savePendingDrafts function, which returns whether it is safe to continue.更新 UI が無期限に待機しないように、バインドされた非同期クリーンアップ。

```tsx
beforeReload: async ({ type }) => {
  if (type === 'switchVersion') {
    const saved = await savePendingDrafts();
    return saved;
  }
  return true;
},
```


## ネイティブ起動チェック {#native-check}

`disableNativeCheck` の既定値は `false` です。ネイティブチェックはコールドスタート後に独立して実行され、JavaScriptを利用できない場合でも復旧用の更新をダウンロードできます。`checkStrategy: null` はこのネットワークリクエストを無効にしません。サーバーの `forceBoot` 指定により、復旧用更新の適用を次回起動まで待機させることもできます。ローカルのロールバック保護は引き続き有効です。詳しくは[強制復旧](/docs/console#rescue)を参照してください。


## CaptureException(エラー、コンテキスト?) {#function-captureexceptionerror-context}

既存のクライアントを使って、捕捉したJavaScriptエラーを報告します。捕捉されなかったエラーは自動的に報告されます。`disableErrorReporting` はエラー報告を無効にし、`disableTelemetry` は関連する送信も停止します。診断に必要な情報だけを含めてください。対応するソースマップを保管し、[エラー診断](/docs/errors)の手順を確認してください。

```tsx
const { client } = useUpdate();
try {
  await submitOrder();
} catch (error) {
  client?.captureException(error, { context: 'checkout' });
}
```


## Android 混合アプリ: setCustomInstanceManager {#updatecontextsetcustominstancemanagerreactinstancemanager-instancemanager}

標準の ReactApplication ではなく ReactInstanceManager を所有する Android ホストの場合は、作成後に同じライブ インスタンスを登録します。これはリロード ターゲットのみを提供します。インスタンスには、バンドル パスとして UpdateContext.getBundleUrl(context) が必要です。標準の RN アプリは、追加のインスタンスを作成せずに [ネイティブ統合](/docs/getting-started#android) に従う必要があります。

```java
import cn.reactnative.modules.update.UpdateContext;

UpdateContext.setCustomInstanceManager(reactInstanceManager);
```