メインコンテンツまでスキップ

デバイスプレビューリンク

device preview linkは、受信者のブラウザーで、アプリのビルドをライブの iOS シミュレーターまたは Android エミュレーター上で開く URL です。リンクを開いた人は、アプリがインストールおよび起動済みで、すぐに操作できる自分専用の新しいデバイスを利用できます。Bitrise アカウント、Xcode、Android Studio、その他のインストールは不要で、必要なのはブラウザーだけです。

代表的な用途はコードレビューです。CI Workflow がアプリをビルドし、そのビルド用のリンクを発行して、プルリクエストに投稿します。レビュアー、デザイナー、リンクを共有したその他の人は、マージされる前に変更を試せます。

  • リンクは、1つのアプリビルドと1つのデバイス構成に対して発行されます。発行時には何も保存されません。リンクは署名付きトークンであり、誰にも開かれなかったリンクにはコストがかかりません。
  • リンクを開くたびに、workspaceに新しいdevice sessionが開始され、デバイスの起動、ビルドのダウンロード、アプリのインストールと起動が行われます。1つのリンクで複数のレビュアーが同時に利用できます。
  • リンクから開かれるセッションは、誰がリンクを発行したかにかかわらず、通常の workspace 所有のセッションです。workspace のすべてのメンバーが、RDE UI の Workspace sessions でセッションを確認および管理でき、個人のセッション一覧には表示されません。パーソナルアクセストークンで発行したリンクでは作成者としてあなたが記録されますが、リンクは Bitrise 外の人とも共有されるため、そのセッションが個人のセッションになることはなく、保存済みの入力や認証情報も引き継がれません。CI から Workspace API token で発行したリンクには、作成者がまったくありません。
  • 誰も一定時間デバイスを見ていないと、デバイスは自動的にシャットダウンします。プレビューデバイスを復元することはできません。リンクを開き直すと、新しいデバイスが起動します。
  • リンクは有効期限が切れると使えなくなります。すでに開いているデバイスには影響しません。

ビルドはシミュレーターまたはエミュレーター用のビルドで、匿名の GET から絶対 https URL で取得できる必要があります。対応する形式については、Supported platformsを参照してください。署名付きで有効期限のあるダウンロード URL も使用でき、閲覧者には表示されませんが、リンクより長く有効である必要があります。URL の期限が切れた後にリンクを開いた閲覧者のデバイスでは、インストールに失敗します。

Bitrise Step Library の Device Preview Step は、次の処理を行います。

  • Workflow 内で先にビルドしたアプリのリンクを作成します。
  • リンクを $BITRISE_DEVICE_PREVIEW_URL としてエクスポートします。
  • 必要に応じて、ビルドが属するプルリクエストにコメントとして投稿します。

ビルド自身の API トークンで認証するため、設定は不要です。Workflow Editor の Step Library から Workflow に追加するか、bitrise.yml の device-preview@1 として追加してください。プレビュー中に Step を Git の URL で参照していた場合は、バージョン管理された更新を受け取れるよう、Step Library ID に切り替えてください。

workflows:
  pr-preview:
    steps:
    - xcode-build-for-simulator@0:
        inputs:
        - project_path: $BITRISE_PROJECT_PATH
        - scheme: $BITRISE_SCHEME
    - deploy-to-bitrise-io@2: {}
    - device-preview@1:
        inputs:
        - app_path: $BITRISE_APP_DIR_PATH.zip
        - post_pr_comment: "true"

Stepは、app_path 入力からプラットフォームを判別します。iOS の場合は .zip、Android の場合は上記の例のように .apk を指定します。app_path は、CI build machine 上のローカルファイルです。Deploy to Bitrise.io Step が Workflow 内で先にそのファイルをアップロード済みの場合、Device Preview Step はその URL を再利用してプレビューリンクを作成します。そうでない場合は、ファイル自体をアップロードし、そこからリンクを作成します。

その他の入力は、以下のリンクオプションに対応しています。device_model、os_version、system_image、link_ttl_hours、auto_terminate_minutes、stack、machine_type、および Android のエミュレーターサイズ指定の入力です。warm_pool_id を指定すると、リンクを開いたときの処理を warm poolから提供します。すべての入力と出力は、Step の README に記載されています。

Stepは、後続の Steps 向けに BITRISE_DEVICE_PREVIEW_URL と BITRISE_DEVICE_PREVIEW_EXPIRES_AT をエクスポートします。URL を Slack に投稿する、チェックに添付する、リリースノートに貼り付けるといった使い方ができます。Step は、リンクを作成できない場合にビルドを失敗させます。プレビューの問題でビルドを止めたくない場合は、is_skippable: true を設定してください。

Pull request のシミュレーター向けビルド

デバイス用ビルドのみを生成するプルリクエスト Workflow には、プレビューできるものがありません。Workflow にシミュレーターまたはエミュレーター用のビルドを追加するか、Pipeline で並列に実行し、その出力を Step に渡してください。

すでに URL があるビルドのリンクを発行します。

bitrise-cli rde preview-link create --device-platform ios --artifact-url https://…/App.zip

このコマンドは、リンク、その ID、有効期限を出力します。--output json を追加すると JSON と同じフィールドが出力され、--artifact-url-stdin を追加するとコマンドラインの代わりにファイルから署名付き URL を読み込めます。

CI や、誰もサインインしていない環境では、Remote Dev Environments アクセス権で作成した Workspace API token で認証します。これを BITRISE_TOKEN として渡し、workspace を明示的に指定してください。workspace トークンは1つの workspace に属しており、それを検索できないためです。

BITRISE_TOKEN=bitwat_… bitrise-cli rde preview-link create --workspace WORKSPACE_ID \
  --device-platform android --artifact-url-stdin < artifact-url.txt

たとえば、「アプリをシミュレーター用にビルドして、デザインチャンネルに投稿できるプレビューリンクをください」のように、普通の言葉で依頼します。エージェントはセッション内でアプリをビルドし、アクセス可能な場所にアップロードして、device_spec と artifact を指定して bitrise_devenv_create_preview_link を呼び出します。ツールは、共有用の URL を返します。

ツールの説明には、プレビューリンクが適切なツールとなる場面、つまり人がアプリを試す場面が記載されています。エージェント自身がデバイスを操作する必要がある場合は、代わりに device session を作成します。

create preview link エンドポイントを呼び出します。RDE API の他のエンドポイントと異なり、パーソナルアクセストークンに加えて Workspace API トークンも使用できます。

curl -X POST "https://api.bitrise.io/rde/v1/workspaces/WORKSPACE_ID/preview-links" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_spec": { "platform": "android" },
    "artifact": {
      "url": "https://…/app.apk",
      "app_name": "My App",
      "build_number": "1234",
      "commit_sha": "0a1b2c3"
    },
    "ttl_seconds": 14400
  }'

レスポンスには、共有可能な url、リンクの ID、expires_at が含まれます。Create device preview link を API リファレンスで参照してください。

デバイスのフィールドは、device session の device options と同じで、プラットフォーム、デバイスモデル、OS バージョンまたはシステムイメージ、Android ではエミュレーターのサイズ指定です。違いは2点あります。プラットフォームとアプリビルドは必須であること、そしてデバイスモデルはリンクの発行時に検証されないため、不明なモデルを指定するとデフォルトのモデルが起動し、閲覧者に通知が表示されることです。

リンク固有のオプションは次のとおりです。

OptionDescription
App name, build number, commit閲覧者ページに表示される表示用メタデータです。レビュアーがどのビルドを見ているかを把握できます。
Link lifetimeリンクを開ける期間です。デフォルトは24時間、最大は72時間です。
Auto-terminate最後の閲覧者が切断してから、デバイスが起動し続ける時間です。デフォルトは60分で、最短は10分です。
Stack and machine typeデバイスが実行される場所です。プラットフォームのデフォルトを使う場合は空のままにします。プラットフォームに合わない値は、リンクの発行時に拒否されます。

プールがない場合、リンクを開くたびに新しいセッションが一から開始されます。マシンのプロビジョニング、セッションのセットアップの実行、シミュレーターまたはエミュレーターの起動が行われ、その後ようやくアプリのダウンロードとインストールが始まります。この起動処理が、レビュアーが待つ 1 ~ 3 分のほとんどを占めています。warm poolを使えばこの待ち時間をなくせます。アプリのデバイスを起動するテンプレートのプールに対してリンクを発行すると、リンクを開くたびに、すでにデバイスが起動した状態のプールのウォームセッションが 1 つ割り当てられるため、クリックからアプリが表示されるまでの時間はアプリのダウンロード時間だけになります。その時点でプールにウォームセッションがない場合は、プールの設定から新しいセッションが作成されるため、リンクは引き続き動作しますが、速度は遅くなります。

プールの設定では、アプリのプラットフォームのデバイスを起動する必要があります。デバイスとマシンはプールによって固定されるため、プールに対してリンクを発行する際は、デバイスモデル、OSバージョン、システムイメージ、エミュレーターのサイズ設定、スタック、マシンタイプを未設定のままにしてください。アプリのプラットフォームは引き続き検証されるため、Androidビルドを iOS プールに対して発行することはできません。

Device Preview Stepで、warm_pool_id にプールの ID を設定します。RDE UIのプールのページ、または bitrise-cli rde warm-pool view からコピーできます。

workflows:
  pr-preview:
    steps:
    - android-build@1:
        inputs:
        - variant: debug
    - deploy-to-bitrise-io@2: {}
    - device-preview@1:
        inputs:
        - app_path: $BITRISE_APK_PATH
        - warm_pool_id: 571eff49-368b-400c-86c3-f4ce49be9159
        - post_pr_comment: "true"

他のクライアントでも、同じプール参照を指定します。

  • CLI: bitrise-cli rde preview-link create --warm-pool POOL --artifact-url URL。POOL にはプールの ID または名前を指定します。
  • AIエージェント(MCP): bitrise_devenv_create_preview_link ツールの warm_pool_id。
  • API: プレビューリンク作成リクエストの warm_pool_id。

プールを使用するリンクでは、次の 2 点が変わります。

  • プールを削除するとリンクが無効になり、以降の操作は、期限切れのリンクと同様に失敗します。リンクを機能させたまま、使用していないデバイスの料金を止めたい場合は、代わりにプールのサイズを 0 に設定してください。
  • プールを使用するリンクは、プールのテンプレートから作成されたセッションを開くため、レビュアーのデバイスでは、そのテンプレートのセットアップスクリプトと入力で設定された内容が実行されます。プールがない場合、リンクはアプリのみがインストールされたまっさらなデバイスを開きます。

受信者に表示される内容Click to copy link​

リンクを開くと、アプリ名、ビルド番号、コミットが表示され、続いてデバイスの起動とアプリのインストールおよび起動の進行状況が表示されます。これには通常1〜3分かかります。その後、閲覧者はデバイスの画面上でタップ、入力、スワイプができ、ホームボタン、アプリスイッチャー、Android の戻るボタン、画面の回転、ライト/ダークの外観切り替え、フル解像度のスクリーンショットのコントロールを利用できます。

2つの more actions が利用できます。

  • Share this device は、このデバイスをそのままの状態で開くリンクをコピーします。2人目の人は、新しくインストールされたデバイスではなく、同じ画面を見ることができます。見つけたばかりのバグを相手に見せるときに使ってください。
  • Delete session は、タイムアウトを待たずにデバイスをすぐに終了します。

リンクの有効期限が切れた後にリンクを開くと、プレビューリンクの期限が切れていることが表示されます。workspace のログイン権限を持つ人は、RDE UI の Workspace sessions で、そのリンクが作成したセッションを引き続き確認できます。

セキュリティと制限Click to copy link​

プレビューリンクはパスワードと同様に扱ってください。URL を持っている人は誰でも workspace 内のデバイスを開くことができ、リンクを取り消すことはできません。リンクは有効期限が切れるまで動作します。リンクはプルリクエストやチームのチャンネルに投稿し、公開の場には決して投稿しないでください。また、有効期間はレビューサイクルが許す範囲で短くしてください。

1つのリンクで発生しうるコストを抑える制限は次のとおりです。

  • リンクは、デフォルトで24時間、最大で72時間有効です。
  • 同時に稼働できるデバイスは、1つのリンクにつき最大5台、workspace につき最大20台です。上限を超える open は、デバイスがシャットダウンするまで拒否されます。
  • 各デバイスは、閲覧者がいない状態で auto-terminate の時間が経過するとシャットダウンし、合計で8時間を超えて動作することはありません。

リンクがすでに開いたデバイスを停止するには、RDE UI の Workspace sessions 一覧からセッションを終了または削除するか、bitrise-cli rde session list --scope workspace を使用してください。漏えいした Workspace API トークンによる新たなリンクの発行を止めるには、トークンを再生成してください。

プレビューリンクを使用するには、workspace で Remote Dev Environments へのアクセスが必要です。Workspace API トークンでリンクを発行できるのは、Remote Dev Environments アクセス権で作成されている場合のみです。

関連情報