Skip to main content
Live Activitiesを使用すると、iOSアプリがロック画面とDynamic Islandに直接リアルタイム更新を表示できます。配送追跡、スポーツスコア、または時間に敏感なトランザクション更新に最適で、アプリを開かずにユーザーに情報を提供し続けます。
AndroidにはAndroid Live通知と呼ばれる同様の機能があります。

要件


セットアップ

これらの手順では、Live Activitiesを迅速にセットアップする方法を説明します。詳細とデザインのカスタマイズについては、AppleのLive Activities開発者ドキュメントを参照してください。

1. Widget Extensionを追加する

Xcodeで、ファイル > 新規 > ターゲット… > Widget Extensionに移動します。

XcodeでアプリのWidget Extensionターゲットを新規追加します。

選択して次へを押します。 名前を入力してWidget Extensionを設定し(例:OneSignalWidget)、Include Live Activityが選択されていることを確認します。次に完了をクリックします。

Live ActivityのWidget Extensionオプション。

スキームをアクティブ化するように求められた場合は、アクティブ化しないをクリックします。

スキームのアクティベーションプロンプト — 「アクティベートしない」を選択します。

2. Info.plistを更新する

メインターゲットのInfo.plistに、キーSupports Live ActivitiesBooleanとして追加し、YESに設定します。

InfoにSupports Live Activitiesキーを追加し、その値をBoolean YESに設定します

プログラムで設定する場合は、次のようになります:
info.plist
Live Activitiesを更新する場合、「優先度」を設定するオプションがあり、Appleはこれを使用して更新の緊急性を判断します。Appleには内部しきい値があり、高優先度フラグを頻繁に使用するリクエストをスロットルします。Live Activitiesのユースケースがより頻繁な高優先度更新に依存している場合、AppleのDeveloper Docsで指示されているように、Info.plistにキーNSSupportsLiveActivitiesFrequentUpdatesをBoolean型でYESとして追加できます。Live Activityがプッシュ予算を超えると、ユーザーにダイアログが表示され、Live Activityを続行することを許可すると、シームレスなユーザーエクスペリエンスのために予算が自動的に増加します。

3. SDKを追加する

ラッパーSDK(例:Flutter)でSPMが有効になっている場合、このステップはスキップできます。OneSignalパッケージはすでに解決されており、すべてのターゲットで利用可能です。
Widget Extensionターゲットで、一般 > フレームワーク、ライブラリ、および埋め込みコンテンツの下にOneSignalFrameworkを追加します:

Widget ExtensionターゲットにOneSignalFrameworkを追加します

4. ウィジェット属性とUIを定義する

your-nameLiveActivity.swiftファイル(例:OneSignalWidgetLiveActivity.swift)を開いて、構造体のプロパティを定義し、ウィジェットUIを変更します。
  • your-nameAttributesは、Live Activityの静的コンテンツを説明します。
  • ContentStateは、Live Activityの動的コンテンツを説明します。
例に従っている場合は、以下のコードをあなたの OneSignalWidgetLiveActivity.swiftファイルにコピーペーストします。
your-nameLiveActivity.swift

5. メインターゲットメンバーシップを許可する

このステップはカスタム属性(例:OneSignalWidgetAttributes)を使用する場合にのみ必要です。DefaultLiveActivityAttributesを使用している場合は、このステップをスキップしてください。このタイプはOneSignal SDKによって提供されており、メインアプリターゲットからすでにアクセス可能です。
your-nameLiveActivity.swiftファイルのターゲットメンバーシップリストにメインアプリターゲットを追加します。これは、メインアプリターゲットがセットアップ呼び出し(ステップ6)でカスタム属性構造体を参照できるようにするために必要です。 Xcodeで、画面の右側にあるInspectorパネルを開きます。ターゲットメンバーシップ内で、**+**ボタンをクリックし、ContentViewとOneSignal初期化コードを含むメインアプリターゲットを選択します。

メインターゲットメンバーシップを許可します

6. AppDelegateにセットアップメソッドを追加する

OneSignal SDK初期化の後、AppDelegateOneSignal.LiveActivities.setupを呼び出します。 OneSignalWidgetAttributesをLive Activity属性構造体の名前に置き換えます。
AppDelegate
これにより、ActivityKit非同期シーケンスを使用して更新を管理および報告します。
アプリで次のシーケンスを直接使用する場合、OneSignal Live Activityの動作に干渉する可能性があります:
  • activityStateUpdates
  • pushTokenUpdates
  • pushToStartTokenUpdates
  • activityUpdates

Live Activityを開始する

デバイスでLive Activityを開始するには2つのオプションがあります:
Push To Start APIリクエストを送信します。すべての名前とIDがウィジェットの構成と正確に一致することを確認してください(パラメーターは大文字小文字を区別します)。何かが欠落しているか、誤って追加された場合、ウィジェットの起動時に問題が発生する可能性があります。上記の例で機能するリクエストの例を次に示します。置き換え:
  • YOUR_APP_IDをOneSignal App IDに置き換えます。
  • YOUR_APP_API_KEYをOneSignal APIキーに置き換えます。
  • OneSignalWidgetAttributesをWidget Attributes構造体の名前に置き換えます。
    curl
提供されたサンプルコードに従っている場合、デバイスのロック画面にLive Activityが表示されます。

ロック画面のLive Activity

push-to-startでLive Activityを正常に開始しました!ユーザーは更新を受け取り続けるために「許可」を選択する必要があります。

Live Activityのクリックを追跡する

OneSignalのクリック追跡を実装することで、ユーザーがLive ActivitiesとDynamic Islandをタップしたときを追跡します。これにより、エンゲージメントを測定し、オプションでユーザーをアプリ内の特定のコンテンツにディープリンクできます。

ステップ1: ウィジェットにクリック追跡を追加する

Live Activityウィジェット内のクリックを追跡したいUIコンポーネントに.onesignalWidgetURL()モディファイアを追加します:
重要な考慮事項:
  • ディープリンク用のURLを渡すか、ナビゲーションなしでクリック追跡のみを行う場合はnilを渡すことができます
  • .onesignalWidgetURL()を使用している場合、ビュー階層にAppleの.widgetURL()モディファイアを含めることはできません
  • 両方のクリックを追跡したい場合は、メインのLive ActivityビューとDynamic Islandの両方にモディファイアを適用します

ステップ2: アプリでURLを処理する

クリックを追跡しユーザーを適切にルーティングするために、アプリにURLハンドリングを追加します:
trackClickAndReturnOriginal()メソッドは、OneSignalでクリックを自動的に追跡し、アプリが処理するためにウィジェットで指定した元のURLを返します。

Live Activityを更新する

Update Live Activity APIを使用してアクティブなウィジェットを更新します。 アクティビティを開始するときに使用したactivity_idと一致させます。 このサンプルリクエストは、定義したactivity_idpush-to-startというタイトルであるため、push-to-startウィジェットを更新します。 click-to-startウィジェットを更新するには、リクエストパスをpush-to-startの代わりにclick-to-startを使用するように更新します。
curl

Live Activity更新

Live Activityを正常に更新しました!Live Activityの更新の詳細については、Update Live Activity APIをご覧ください。

Live Activityを終了する

同じUpdate Live Activity APIを使用して、"event": "end"を設定することでLive Activityを終了できます。
curl
Live Activityが終了する他の方法:
  • SDK のexit()メソッドを使用する。
  • ユーザーが手動でLive Activityをスワイプして削除する。
  • ユーザーがiOS設定でLive Activitiesの権限を取り消す。

Live Activity終了

Live Activityを正常に終了し、例を完了しました!

ベストプラクティスと推奨事項

デザインに関する考慮事項

  • AppleのLive Activities Human Interface Guidelinesに従ってください。
    • 重要な情報を優先して、一目で理解しやすくします。
    • Dynamic Islandに注意を引く要素をアプリに追加しないでください。
    • マージンを使用し、要素間のスペースを維持します。
    • 背景に太字の色を使用します。ライトモードとダークモードの両方をデザインします。

機能性

フォールバックメッセージの設定

Live Activityが開始された後、ユーザーが更新を受信できない場合は、アプリを開くことでアクティビティが更新されます。最初の更新を送信することを見込んでいる時点以降の将来の日時にstale dateを設定します。更新を受信していないユーザーには、代わりにフォールバックメッセージが表示されます。 ウィジェットUIでこの「stale」状態をリッスンして、フォールバックメッセージを表示できます:
フォールバックメッセージを表示しているLive Activityウィジェット

Live Activityがstaleになったときに表示されるフォールバックメッセージ。


FAQ

高優先度更新の予算は何ですか?

Appleは高優先度(priority: 10)更新に固定制限を提供していませんが、動的なシステムレベルの予算を適用しています。短期間に高優先度更新を送信しすぎると、更新が遅延またはドロップされるスロットリングが発生する可能性があります。 スロットリングのリスクを軽減するには:
  • 優先度レベルを混在させる:Appleは、バランスを取るためにpriority: 5(標準)とpriority: 10(高)の両方を使用することを推奨しています。
  • priority: 10は、時間に敏感または重要な更新のみに予約します(例:注文ステータスの変更、ゲームスコア)。
ユースケースで頻繁な更新が必要な場合:
  • アプリのInfo.plistファイルにNSSupportsLiveActivitiesFrequentUpdatesキーをBoolean YESとして追加します。
  • この予算を超えると、iOSはユーザーに追加の更新を許可するように促す場合があります。ユーザーが同意すると、Appleはシームレスなエクスペリエンスを維持するために、許可された更新制限を自動的に拡張します。
詳細については、AppleのDeveloper Docsを参照してください。

メインアプリからLive Activity更新を読み取ることはできますか?

はい。デバッグまたはUI同期のために更新を監視できます:
ライフサイクルの変更を追跡:

APIが400を返し、サブスクライバー制限を超えているというエラーメッセージが表示されました。どうすればよいですか?

プッシュサブスクライバー数がプランのプッシュサブスクライバー数を超えている場合は、アカウントを次のプランにアップグレードするか、support@onesignal.comにお問い合わせください。最新のプラン詳細については、こちらをご覧ください

プッシュとLive Activitiesの両方を送信しないようにするにはどうすればよいですか?

アプリケーションは既に一連のプッシュ通知を送信している可能性があり、設計したLive Activityがこれらのプッシュ通知の必要性を置き換えます。たとえば、プッシュ経由でスコア更新を送信している場合、これをLive Activityで置き換えることができます。 ユーザーがメッセージを受け取りすぎないようにするために、ユーザーがLive Activityにオプトインするときにデータタグを追加することをお勧めします。このデータタグを追加することで、同じまたは類似のコンテンツを含む可能性のあるプッシュメッセージからこのデータタグを持つユーザーを除外できます。詳細については、データタグセグメントをご覧ください。

トラブルシューティング

受信者なし

Live Activityを開始または更新しようとするときにユーザーが見つかるようにするには、アクティビティタイプ、ウィジェット、およびcURLリクエストのすべてに一致する値があることを確認する必要があります。
  1. リクエストのパスパラメーターをチェックして、正しくフォーマットされたリクエストをサーバーに送信していることを確認します。App IDはOneSignal.Initializeメソッドで使用したApp IDと一致する必要があり、アクティビティタイプはLive Activityファイルで定義したタイプと一致する必要があります。
  2. Push To Start APIリクエストの本文には、次のパラメーターが必要です:
  • event: "start"
  • event_updates: アクティビティタイプの下の構造体で定義した動的データで、ウィジェットで使用されます。リクエスト、タイプ、ウィジェット間で大文字小文字と変数がすべて一致することを確認してください。
  • event_attributes: 静的データはEvent Updatesと同じロジックに従い、使用中のすべての変数を含める必要があり、Live Activityのすべての部分とリクエスト全体で一致する必要があります
  • activity_id: これによりウィジェットにIDが割り当てられ、ユーザーのデバイスで起動された後にアクティビティを更新するために使用されます。
  • name: Live Activity名。
  • contents: プッシュ送信に必要なメッセージコンテンツ。
  • headings: プッシュ送信に必要なメッセージ見出し。
  • included_segmentsのようなターゲティングパラメーター。利用可能なオプション

アクティビティが送信されたが、受信されない

  1. リクエストが正しくフォーマットされていることを確認します。ウィジェットで使用されているフィールドが省略されている場合、アクティビティが起動または更新されない可能性があります。
  2. APIリクエストで、設定しているpriorityレベルを確認します。これを10(最高優先度)に設定している場合は、5に下げて再度テストしてください。Appleは独自の内部レート制限に従って、頻繁に送信されるリクエストをスロットルします。
ユースケースでより頻繁な更新が必要な場合は、AppleのDeveloper Docsで指示されているように、Info.plistにBoolean型でYESに設定されたNSSupportsLiveActivitiesFrequentUpdatesキーを追加します。Live Activityがプッシュ予算を超えると、ユーザーにダイアログが表示され、ユーザーがLive Activityの継続を許可すると、シームレスなユーザーエクスペリエンスのために予算が自動的に増加します。
サポートが必要ですか?サポートチームとチャットするか、support@onesignal.comにメールしてください以下を含めてください:
  • 発生している問題の詳細と再現手順(利用可能な場合)
  • OneSignal App ID
  • 該当する場合は、External IDまたはSubscription ID
  • 該当する場合は、OneSignalダッシュボードでテストしたメッセージのURL
  • 関連するログまたはエラーメッセージ
お気軽にお問い合わせください!