プッシュ通知によるライブアクティビティの更新

プッシュ通知によるライブアクティビティの更新

Apple Push Notificationサービス（APNs）を通じてコンテンツをプッシュする際に、リモートでアプリのライブアクティビティを更新する方法を紹介します。最初のライブアクティビティのためのプッシュをローカルで設定する方法を紹介し、実装をすばやく反復する方法について解説するとともに、プッシュの優先順位を決定し、アラートアップデートを設定するためのベストプラクティスや、関連性スコアと古くなった日付を使用してライブアクティビティをさらに改善する方法について解説します。このセッションを最大限に活用するためには、ActivityKitとライブアクティビティに精通していることが望ましいです。ライブアクティビティの概要については「ActivityKiについてt」をご確認ください。

関連する章
- 0:00 - Intro
- 2:10 - Preparations
- 5:58 - First push update
- 11:04 - Priority and alerts
- 15:40 - Enhancements
- 17:27 - Wrap-up
リソース
関連ビデオ

WWDC24
- ライブアクティビティのブロードキャスト更新
WWDC23
ダウンロード

♪ ♪
Jeff: Live Activities TeamのエンジニアのJeffですプッシュ通知によるライブアクティビティの更新について共有できることを嬉しく思いますライブアクティビティは進行中のアクティビティに関する情報を一目で確認できるように表示する素晴らしい方法です ActivityKitはアプリがライブアクティビティを開始　更新　終了できるようにしますそしてWidgetKitとSwiftUIを利用することでユーザに情報を表示する UIを構築することができます
これらの技術をもっと知りたい場合はこちらをご確認ください Canによる「ActivityKitについて」というセッションですこのセッションで Emoji Rangersに新しいライブアクティビティを追加してヒーローの冒険のステータスを表示できますでも主人公に仲間がいればもっと楽しくなると思いますそこで複数のユーザがヒーローとチームを組み一緒に冒険をすることができる新機能を追加したいと思います最高の体験を提供するためにライブアクティビティを更新しチーム内の全ヒーローのイベントが表示されるように更新します
そのためにデバイス上でアドベンチャーの追跡をするのではなくサーバーを導入しますサーバーによってライブアクティビティを最新の状態に保てるようにします計算はサーバー上で行われるのでアプリはライブアクティビティを更新するためにフォアグラウンドのランタイムを必要としませんこれによりユーザのバッテリー寿命に与える影響が少なくなります ActivityKitのプッシュ通知でライブアクティビティを更新するのはこの機能を実行する素晴らしい方法になる見込みですこのセッションではまずプッシュアップデートでライブアクティビティを更新できるようにするために必要な準備について説明します次に最初のプッシュアップデートをコンピューターから送信しますそして更新時のプライオリティとユーザへのアラート方法の違いについて掘り下げます最後にプッシュアップデートをさらにレベルアップさせるために追加できる機能強化について説明しますさっそく準備に取りかかりましょうプッシュアップデートでライブアクティビティの更新を始める前にアプリとサーバーがAppleプッシュ通知サービスとどのようにやりとりするかを理解しておくと便利ですすべてはアプリから始まります新しいアクティビティが開始されると ActivityKitは Appleプッシュ通知サービス（APNs）からプッシュトークンを取得しますこのプッシュトークンはリクエストしたライブアクティビティごとに固有ですそのためアプリがプッシュアップデートの送信を開始する前にそれをサーバーに送信する必要がありますライブアクティビティを更新する必要があるときは常にサーバーはAPNsにトークンを使ってプッシュリクエストを送信します最後にAPNsはペイロードをデバイスに送信し Widget Extentionを起動してUIをレンダリングします
この新機能をサポートするために APNsは新しい "liveactivity" プッシュタイプを導入しましたこのプッシュタイプは APNsにトークンベースで接続しているサーバーでのみ利用できますプッシュリクエストの送信について詳しくは「APNsへの通知リクエストの送信」ドキュメントを参照してくださいトークンベースの接続に関しては「APNsへのトークンベース接続の確立」を参照してください次のステップはライブアクティビティがプッシュアップデートを受信するようにアプリを修正することです Xcodeでアプリのターゲットに移動し "Signing & Capabilities" タブでプッシュ通知機能を追加しますこれによりActivityKitがアプリに代わってプッシュトークンをリクエスト可能になりますこれからコードに入りたいと思いますライブアクティビティをリクエストする Emoji Rangersのコードの一部分ですアクティビティリクエストメソッドにアドベンチャーの属性とコンテンツの初期状態を与えますプッシュの受信をサポートするメソッドにpushTypeパラメータを追加しその値を "token" に設定しますこれによりActivityKitはライブアクティビティの作成時にプッシュトークンを要求できますアクティビティが作成されたらアプリはプッシュトークンをサーバーに送信する必要がありますアクティビティタイプにはプッシュトークンに同期的にアクセスできる pushTokenプロパティがありますただしアクティビティ作成直後はアクセスしないでください得られる値はほとんどの場合ゼロですこれは非同期処理だからですまたアクティビティのライフタイム中にシステムがプッシュトークンを更新することも可能ですそのためアプリはそれに応じて対応する必要がありますプッシュトークンを適切に処理する方法はまず非同期タスクを作成しアクティビティのpushToken更新の非同期配列から値を観察する for-awaitループを開始します forループ内のコードはライブアクティビティに新しいプッシュトークンがあるたびに実行されますここで非同期のforループを使うことが重要なのは最初のプッシュトークンだけでなくそれ以降のプッシュトークンの更新も処理できるようにするためですトークンを受け取ったらそれを16進文字列に変換しデバッグコンソールに記録しますこれは次のテストに役立つはずですそして最後にアプリに必要な他のデータと一緒にプッシュトークンをサーバーに送信しますプッシュトークンはアクティビティごとに異なりユーザが開始するライブアクティビティごとに追跡することが重要ですまたシステムが既存のアクティビティに新しいプッシュトークンを要求するとアプリはフォアグラウンドで実行されます新しいプッシュトークンをサーバーに正しく送信されるように古いプッシュトークンを無効にすることが重要です準備が完了し最初のプッシュアップデートを送信する時が来ましたプッシュアップデートを送信するにはAPNに HTTPリクエストを送信する必要がありますリクエストはAPNsヘッダと APNsペイロードの2つの部分で構成されます通常のHTTPヘッダに加え 3つのヘッダを提供することが必要です 1つ目はapns-push-typeで値は"liveactivity"です次はapns-topicでアプリのバンドルIDに ".push-type.liveactivity"が続きます 3つ目はapns-priorityで 5か10の値を指定します 5はこのプッシュリクエストの優先度が低いことを示し 10は優先度が高いことを示しますライブアクティビティが即座に更新されるためテスト中は高い優先順位を使います最初のAPNsペイロードは 3つのフィールドで構成されています 1つ目は "timestamp" で 1970年からの経過秒ですシステムはタイムスタンプを使用して常に最新のコンテンツ状態をレンダリングするようにしています 2つ目は "event"ですライブアクティビティで実行したいアクションですその値は"update"か"end"のどちらかですこの最初のAPNsリクエストでは "update" に設定すべきでしょう 3番目のフィールドは "content-state" ですこれはアクティビティのコンテンツステートタイプにデコードできるJSONオブジェクトですコンテンツの状態を確実に取得するためにアプリ内からFoundationの JSONEncoder タイプを使用できますここではライブアクティビティの Content Stateインスタンスを作成しそしてJSONEncoderをインスタンス化します最後にコンテンツステートを JSONデータにエンコードしその文字列表現をコンソールに記録しますキャメルケースのキーを持つこの JSON出力は私が予想していた通りですコンテンツステートのJSONは常にデフォルトのデコードストラテジーを持つ JSONDecoderを使用してデコードされますそのためコンテンツステートをエンコードする際にはカスタムエンコーディングストラテジーを設定しないことです設定してあるとJSONは不一致となりシステムはライブアクティビティの更新に失敗してしまいますプッシュリクエストの内容がわかったところで次はプッシュリクエストの送信テストです開発中に素早く繰り返せることに大賛成ですですのでサーバーを変更することなくライブアクティビティのプッシュ通知をテストするのが良いでしょう私の端末から直接APNsにプッシュリクエストを送ることで実現しますこれを実行するためにコマンドラインを設定します「コマンドラインツールによるプッシュ通知の送信」をご確認ください「トークンを使ったプッシュ通知の送信」のセクションの指示に従っていることを確認してください認証トークン変数をプリントすればすべてが正しく設定されていることをすぐに確認できます次に必要な情報はプッシュトークンです前のセクションではプッシュトークンをコンソールに記録するコードを追加しましたですのでそこから取ってこようと思ってます同じアプローチを取った場合アプリをデバイスにデプロイしライブアクティビティを開始しますアプリはアクティビティが開始された直後にプッシュトークンを記録しますプッシュトークンをコピーしターミナルでアクティビティプッシュトークン変数として設定します APNsリクエストを送信するには curlコマンドを実行しますこれは私がアドベンチャーライブアクティビティ用に作ったものです「apns-topic」ヘッダにアプリのバンドルIDの後にプッシュタイプのサフィックスが設定されますそして「apns-push-type 」ヘッダは "liveactivity" に設定されます第三に「apns-priority 」が10に設定されているのでこのリクエストはすぐに配信されます最後のHTTPヘッダ "authorization" には "bearer" が設定されその後に認証トークン変数が続きますデータに関してはAPNsのペイロード全体が含まれています秒単位まで正確な数字を保証するために dateコマンドを使ってタイムスタンプを自動的に作成しています最後にURLについてHTTP2を使用していることを確認してください。そしてURLの最後に前のステップで設定したアクティビティプッシュトークン変数を参照しますこれで終わりですこのcurlコマンドを実行するとライブアクティビティはペイロードで提供された新しいコンテンツステートで更新されますライブアクティビティが更新されると思っていたのに更新されないことがあります curlコマンドの実行時にエラーレスポンスがないことを確認すべきですエラーはリクエストのフィールドが正しくないか環境設定時に問題があったのか環境設定時に問題があった可能性があります APNsが正常な応答を返したにもかかわらずライブアクティビティが更新されない場合は Consoleアプリを使用してデバイスのログを表示し問題の特定を試みることができます関連するログを持つ可能性のあるプロセスはliveactivitiesd apsd chronodですライブアクティビティがプッシュ通知でどのように更新されるかに満足したら本物のプッシュアップデートを送信し始めるためにサーバーを変更する時ですそしてユーザ体験をデザインする上で重要な部分であるプライオリティとアラートに行き着きます最高のユーザ体験を保証するためには各アップデートのプッシュプライオリティを正しく選択することが重要です常に優先して使用することを考慮すべきなのはロープライオリティですプライオリティの低いアップデートは臨機応変に配信されるためユーザのバッテリー寿命への影響を低減しますしかしこれはプッシュ要求が送信されたときにライブアクティビティがすぐに更新されない可能性があることを意味しますですから時間的な制約の少ない更新にはロープライオリティを使うべきです私のアドベンチャーライブアクティビティでは共通の戦利品を見つけたりヒーローが多少のヘルスポイントを回復するようなアップデートはユーザの即時の注意を必要としませんだからこそロープライオリティのアップデートを使うのに最適なのですロープライオリティを使うもう一つの利点は送信できる更新回数に制限がないことですこれを利用するためにはライブアクティビティの更新の大半にロープライオリティを使用する必要があります一方でヒーローが倒されたときや大きなボスを倒したときなどユーザの即時の注意を必要とする更新もありますこのような場合はハイプラオリティのアップデートを選びますハイプライオリティのアップデートは即座に配信されますだからこそ一刻を争うアップデートに最適なのですしかしユーザのバッテリー寿命に影響を与えるためシステムはデバイスの状態に応じて予算を課しますアプリが予算を超過した場合プッシュアップデートが制限されユーザ体験に多大な影響を与えますご自身のアプリのことはご自身が一番よく知っていらっしゃるはずですのでどのプライオリティをどのアップデートに使うべきかを慎重に検討することが重要です「Emoji Rangers」ではパーティが次々と大ボスと戦う特殊な冒険を紹介しますこの集中的なライブアクティビティで最高のユーザ体験を提供するためにはサーバーがハイプライオリティのプッシュを頻繁に送信して最新状態を維持する必要がありますこのためにライブアクティビティの頻繁な更新機能を有効にしますこの機能を有効にするとアプリの更新予算が高くなりライブアクティビティの更新がスロットルされにくくなりますこの機能を採用するには info.plistに NSSupportsLiveActivitiesFrequentUpdates という新しいキーを追加しその値をYESに設定しますユーザは設定アプリでライブアクティビティとは別にこの頻繁なアップデート機能を無効にすることができますそこでActivityAuthorizationInfo frequentPushesEnabledプロパティにアクセスすることでこの機能が有効かどうかを検出できますサーバーはこの値に応じて更新頻度を調整すべきですのでプッシュ更新の送信を開始する前にサーバーにこの値を送信していることを確認してくださいこの値をチェックするのはアクティビティ開始後一度だけで大丈夫ですこの値が変更されるとシステムは進行中のすべてのアクティビティを終了するのでサーバーが頻繁に更新が切り替わることを心配する必要はないですアドベンチャーライブアクティビティではヒーローが倒されたとき即座に更新するだけでなくユーザの注意を引きすぐにアプリに入って回復薬を使えるようにしたいですそのために3つのフィールドを持つ "alert" オブジェクトをペイロードに追加します "title" は通知のタイトルになります "body" はアップデートについての短いメッセージになります "sound" はアラートが起動されたときに再生されるサウンドを示します Emoji Rangersは複数の言語に対応していますので英語でのアラート送信だけは理想的ではありませんサーバーでは非常に扱いにくいです幸いにアラートオブジェクトの "title" と "body" フィールドを設定する別の方法があります文字列を渡す代わりにローカライズされた文字列オブジェクトとして設定することができます "loc-key" フィールドにはアプリのローカライゼーションファイルで見つけられるローカライゼーションキーを指定します "loc-args" フィールドはローカライズされた文字列に挿入される値のリストになりますこれでデバイスはユーザの地域に応じて通知を自動的にローカライズしますアラートに最後のタッチを加えるためにカスタムサウンドを追加したいと思いますそのためにはまずサウンドファイルをリソースとしてアプリのターゲットに追加する必要があり次にアラートオブジェクトの "sound" フィールドを私のサウンドのファイル名に設定しますこれで完成ですアラートが見た目もサウンドも素晴らしくなりましたこれからはライブアクティビティのユーザ体験に磨きをかけて改良を加えていくつもりですアドベンチャーが終わったらライブアクティビティを終了させ一定時間後に解散させたいですイベントを "end" に設定したプッシュペイロードを送信して行いますライブアクティビティをロック画面から削除するタイミングを制御したいのでカスタムの "dismissal-date" を設定しますこのフィールドを省くことでライブアクティビティを終了させるタイミングをシステムに任せることができます "dismissal-date" の値は1970年からの経過秒でなければなりませんまたライブアクティビティに最終的な更新のための最終ステートを提供しますこれはオプションで省略した場合にアクティビティは前のコンテンツステートを表示し続けます時々ユーザのデバイスプッシュ通知の受信に不具合が発生することがありますそしてアドベンチャーライブアクティビティは未だに古いヘルス値を表示しているかもしれないですこのようなシナリオではライブアクティビティのUIで不正確な情報が表示される可能性があることをユーザに警告したいと思いますそのためにペイロードに "stale-date"フィールドを追加しますこの日付を使用して古くなったというビューをレンダリングするタイミングを決定します Widget Extensionで宣言されたアクティビティ設定から古いビューを提供することができますビューがActivityViewContextの isStaleプロパティの値に反応するようにします同時に複数のアドベンチャーライブアクティビティがある場合ロック画面に正しく表示したいですより重要なアップデートがあるものはトップに近く最も重要なものはDynamic Islandにあるはずですオプションの関連性スコアフィールドを提供することでこれをアレンジできます数字が大きいほど関連性が高いことを示しますライブアクティビティを更新する方法がお分かりいただけたと思いますアプリにプッシュ通知を追加しましょう最初にすべきことはサーバーとアプリの設定です ActivityKitのプッシュ通知に対応させますターミナルからプッシュアップデートを送信するテストをして素早くイテレートしそれで満足したらエンドツーエンドサポートの導入を開始します一方ユーザ体験を念頭に置くべき適切なプライオリティを使用し必要に応じてユーザにアラートをします一緒にライブアクティビティについて楽しく学んでいただけたなら幸いですみなさんがDynamic Islandとロック画面に持ち込まれるクリエイティブなアイデアを見るのが待ち遠しいです
ご視聴ありがとうございました ♪ ♪

func startActivity(hero: EmojiRanger) throws {
    let adventure = AdventureAttributes(hero: hero)
    let initialState = AdventureAttributes.ContentState(
        currentHealthLevel: hero.healthLevel,
        eventDescription: "Adventure has begun!"
    )

    let activity = try Activity.request(
        attributes: adventure,
        content: .init(state: initialState, staleDate: nil),
        pushType: .token
    )

    Task {
        for await pushToken in activity.pushTokenUpdates {
            let pushTokenString = pushToken.reduce("") { $0 + String(format: "%02x", $1) }
            
            Logger().log("New push token: \(pushTokenString)")
            
            try await self.sendPushToken(hero: hero, pushTokenString: pushTokenString)
        }
    }
}

6:54 - APNs push payload: Updating

{
    "aps": {
        "timestamp": 1685952000,
        "event": "update",
        "content-state": {
            "currentHealthLevel": 0.941,
            "eventDescription": "Power Panda found a sword!"
        }
    }
}

7:37 - Printing content state JSON

let contentState = AdventureAttributes.ContentState(
    currentHealthLevel: 0.941,
    eventDescription: "Power Panda found a sword!"
)

let encoder = JSONEncoder()
encoder.outputFormatting = .prettyPrinted

let json = try! encoder.encode(contentState)
Logger().log("\(String(data: json, encoding: .utf8)!)")

9:18 - Terminal: Constructing an APNs request with curl

curl \
  --header "apns-topic: com.example.apple-samplecode.Emoji-Rangers.push-type.liveactivity" \
  --header "apns-push-type: liveactivity" \
  --header "apns-priority: 10" \
  --header "authorization: bearer $AUTHENTICATION_TOKEN" \
  --data '{
      "aps": {
          "timestamp": '$(date +%s)',
          "event": "update",
          "content-state": {
              "currentHealthLevel": 0.941,
              "eventDescription": "Power Panda found a sword!"
          }
      }
  }' \
  --http2 https://api.sandbox.push.apple.com/3/device/$ACTIVITY_PUSH_TOKEN

14:21 - APNs push payload: Alerting

{
    "aps": {
        "timestamp": 1685952000,
        "event": "update",
        "content-state": {
            "currentHealthLevel": 0.0,
            "eventDescription": "Power Panda has been knocked down!"
        },
        "alert": {
            "title": "Power Panda is knocked down!",
            "body": "Use a potion to heal Power Panda!",
            "sound": "default"
        }
    }
}

14:56 - APNs push payload: Alert localization

{
    "aps": {
        "timestamp": 1685952000,
        "event": "update",
        "content-state": {
            "currentHealthLevel": 0.0,
            "eventDescription": "Power Panda has been knocked down!"
        },
        "alert": {
            "title": {
                "loc-key": "%@ is knocked down!",
                "loc-args": ["Power Panda"]
            },
            "body": {
                "loc-key": "Use a potion to heal %@!",
                "loc-args": ["Power Panda"]
            },
            "sound": "HeroDown.mp4"
        }
    }
}

15:25 - APNs push payload: Alert sound

{
    "aps": {
        "timestamp": 1685952000,
        "event": "update",
        "content-state": {
            "currentHealthLevel": 0.0,
            "eventDescription": "Power Panda has been knocked down!"
        },
        "alert": {
            "title": {
                "loc-key": "%@ is knocked down!",
                "loc-args": ["Power Panda"]
            },
            "body": {
                "loc-key": "Use a potion to heal %@!",
                "loc-args": ["Power Panda"]
            },
            "sound": "HeroDown.mp4"
        }
    }
}

15:52 - APNs push payload: Dismissal

{
    "aps": {
        "timestamp": 1685952000,
        "event": "end",
        "dismissal-date": 1685959200,
        "content-state": {
            "currentHealthLevel": 0.23,
            "eventDescription": "Adventure over! Power Panda is taking a nap."
        }
    }
}

16:44 - APNs push payload: Stale date

{
    "aps": {
        "timestamp": 1685952000,
        "event": "update",
        "stale-date": 1685959200,
        "content-state": {
            "currentHealthLevel": 0.79,
            "eventDescription": "Egghead is in the woods and lost connection."
        }
    }
}

16:54 - Displaying a stale Live Activity UI

struct AdventureActivityConfiguration: Widget {
    
    var body: some WidgetConfiguration {
        
        ActivityConfiguration(for: AdventureAttributes.self) { context in
            AdventureLiveActivityView(
                hero: context.attributes.hero,
                isStale: context.isStale,
                contentState: context.state
            )
            .activityBackgroundTint(Color.gameWidgetBackground)
        }  dynamicIsland: { context in
            // ...
        }
        
    }
    
}

17:19 - APNs push payload: Relevance score

{
    "aps": {
        "timestamp": 1685952000,
        "event": "update",
        "relevance-score": 100,
        "content-state": {
            "currentHealthLevel": 0.941,
            "eventDescription": "Power Panda found a sword!"
        }
    }
}

特定のトピックをお探しの場合は、上にトピックを入力すると、関連するトピックにすばやく移動できます。

クエリの送信中にエラーが発生しました。インターネット接続を確認して、もう一度お試しください。

関連する章

リソース

関連ビデオ

WWDC24

WWDC23