SDK APIリファレンス

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

概要

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

• Pakta クライアント クラスと ClientOptions

• UpdateProvider (別名 PaktaProvider) React 統合

• useUpdate() / useUpdateProgress() / usePakta() フック

• メタデータとクラッシュレポートの相関関係を更新します ・UpdateErrorタイプとイベントモデル

クライアントクラス

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' });

クライアントオプション

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

React 統合

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:

CheckResult とバージョン情報

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 — 未登録のフィンガープリント (厳密なチャネル配信の下で現在のバージョンに保持されます)。

メタデータとクラッシュ相関関係

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 タグに対応するキーと値のペアを構築します。

エラーとイベント

• UpdateError は、安定した機械読み取り可能な code (UpdateErrorCode) を搭載しています。

• EventData (logger コールバック) には、エラーの詳細を含む type (checking、downloading、downloadSuccess、rollback、markSuccess、errorUpdate など) が含まれます。

• JavaScriptエラーの報告とスタックトレースの復元については、エラー診断を参照してください。

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

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

checkUpdate(パラメータ?)

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

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

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) {
  }
}

ダウンロードアップデート(情報?)

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

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

const { updateInfo, downloadUpdate } = useUpdate();

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

downloadAndInstallApk(url)

完全な 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、署名、バージョンを確認してください。配布にストアのアップグレードが必要な場合は、代わりにアプリのストア リンクを使用してください。

downloadAndInstallApk(url: string): Promise<void>

<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />

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>
  );
}

マーク成功()

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

markSuccess(): Promise<boolean | undefined>

autoMarkSuccess: false,

const { markSuccess } = useUpdate();

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

currentVersionInfo

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

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

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

getCurrentVersionInfo()

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

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

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

restartApp()

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

restartApp(): Promise<void>

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

resetToPackagedBundle(options?)

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

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

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

switchVersion(情報?)

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

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

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

switchVersionLater(情報?)

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

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

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

parseTestQrCode(コード)

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

parseTestQrCode(code: string | UpdateTestPayload): boolean

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

useUpdateProgress()

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

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

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

const { lastError, dismissError } = useUpdate();

カスタム更新 UI を構築する

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

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

フックの確認、ダウンロード、リロード

既存のクライアントにフックを追加します。 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 が無期限に待機しないように、バインドされた非同期クリーンアップ。

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

ネイティブ起動チェック

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

CaptureException(エラー、コンテキスト?)

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

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

Android 混合アプリ: setCustomInstanceManager

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

import cn.reactnative.modules.update.UpdateContext;

UpdateContext.setCustomInstanceManager(reactInstanceManager);