iOS SDK

新しい管理型SDKの簡単連携

import KitsPush

// Once on MainActor, after wiring the AppDelegate bridge:
try Kits.initialize(publicKey: publicKey)
// Development-signed app instead:
// try Kits.initialize(publicKey: publicKey, options: KitsOptions(ios: KitsIOSOptions(apnsEnvironment: .sandbox)))

SDKが本番URLと既定ストレージを提供し、認証設定をダッシュボードから読みます。更新版SDKはユーザー・イベント・活動の収集を既定で有効にし、保存済みの収集拒否を維持します。同意前はcollectionEnabled=falseで収集を保留できます。既存アプリは更新や鍵交換で以前のnamespaceを維持してください。APNsの既定はproductionで、開発署名ではsandboxを明示します。

APNsトークンの転送にはKitsPushAppDelegateの継承またはSDK READMEのAppDelegate転送ブリッジが必要です。SwiftUIはUIApplicationDelegateAdaptorを使い、Sceneを使う場合はクリックも転送します。初期化だけでアプリdelegateは置き換わりません。

同意前に収集を保留するには、初期化オプションでcollectionEnabled=falseを指定します。同意後はKits.setCollectionEnabled(true)で開始し、falseで停止します。通知の受信拒否やサーバーに保存済みの記録の削除とは別です。個別機能で明示したfalseは統合設定で有効にしても維持します。iOS拡張の受信報告は別途設定します。

Android固有設定はandroid: KitsAndroidOptions（FCMモード・通知リソース）、iOS固有設定はios: KitsIOSOptions（APNs環境・delegate連携）にまとめます。shouldDisplayはフォアグラウンド表示と新Android SDKによる表示を制御しますが、iOSや旧Android SDKでOSが表示するバックグラウンド通知は遮断できません。初期化だけでは権限を要求しません。

以下のcore専用設定・OSコールバック例は手動の低レベル連携を維持する場合のみ使います。上記の管理型初期化は、この連携をSDKが担当します。

1. Swift Packageを追加する

運営者から検証済みのkits-iosソースまたは承認済みのパッケージの場所を入手してください。この文書では、未確認の公開リポジトリやリリースURLは案内していません。XcodeのAdd Package Dependencies → Add Localで/path/to/kits-iosを選び、アプリのターゲットにKitsPushを追加します。

2. 設定とAPNs環境を確認する

import KitsPush
import UIKit

// Legacy core integration only: keep this app's existing namespace unchanged.
// New integrations use Kits.initialize(publicKey:); the SDK manages storage.
let configuration = try KitsPushConfiguration(
    publicKey: configuredPublicKey,
    storageNamespace: configuredStorageNamespace,
    apnsEnvironment: configuredAPNsEnvironment
)
let kitsPush = try await KitsPushClient.configure(configuration)
await MainActor.run {
    UIApplication.shared.registerForRemoteNotifications()
}

configuredPublicKeyとconfiguredStorageNamespaceには、対象のアプリ環境の設定値を使います。configuredAPNsEnvironmentは、署名のaps-environmentに合わせてKitsAPNsEnvironment.sandboxまたは.productionにします。アプリにはPush Notifications capabilityと、対応する署名設定が必要です。

3. 今回の起動で取得したAPNsトークンを渡す

起動するたびにregisterForRemoteNotificationsを呼び出し、その起動のdelegateコールバックで得たトークンを渡してください。保存済みの古いトークンでは代用しません。以下は既存のdelegateに追加する部分例です。クライアントのライフサイクルはアプリ側で管理します。

// In your existing UIApplicationDelegate; kitsPush is the configured client.
func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    Task { _ = await kitsPush.registerAPNsToken(deviceToken) }
}

// Observe acknowledgement separately from the local .queued result.
for await state in kitsPush.syncStates() {
    if case .synced = state {
        // Latest desired device state acknowledged by Kits.
    }
}

4. 通知delegateをアプリで管理する

• UNUserNotificationCenterDelegateはアプリ側で管理します。フォアグラウンド通知ではhandleWillPresent、通知への応答ではhandleNotificationResponseを呼び出します。
• 戻り値がnilならKitsの通知ではないため、既存のハンドラーに渡します。OSのcompletion handlerは、どの経路でも必ず1回だけ呼び出してください。画面遷移を待つ間、呼び出しを保留しないでください。
• 実際のOS権限をreportPermissionに、アプリ内の受信設定をsetPushPreferenceに渡します。SDKが代わりに同意を得たり、リンクを開いたりすることはありません。
• queuedはローカルへの保存完了を示します。サーバーへの反映はsyncStatesのsyncedで確認し、必要に応じてsynchronizeで同期を要求してください。

基本セグメントと SDK タグ

この機能に対応した SDK とサーバーを使用してください。SDK はアプリバージョン・端末言語・最初と最新のセッション・セッション数・累積フォアグラウンド時間を報告します。初期化のみではセッションを開始せず、実際のフォアグラウンド移行を観測します。

登録と現在のユーザーの紐付けが完了してからタグを設定してください。SDK タグにはバックエンドの属性定義 API は不要です。キーが自動で表示され、ログアウトなどで紐付けが変わると以前のタグは削除されます。

let result = await kitsPush.setTags(["interest": "travel"])
let removal = await kitsPush.removeTags(["interest"])

上の2行は設定と削除の別々の操作例です。

ダッシュボードのセグメントで基本フィルターまたは SDK タグを選び、プレビューを確認します。新しいセグメントは匿名端末を含められ、一致するプッシュ購読にのみ送信します。テスト端末の指定は管理者がダッシュボードで行います。

任意：実際の受信・タップの観測

収集の既定値を更新したSDKソースではnotificationEventsEnabledとpersistNotificationEventsが既定でtrueです。公開済みの旧版とは異なる場合があるため、導入するリリースを確認してください。メッセージのtrack_events=trueは別途必要で、省略したAPIフィールドや保存済み下書きのfalseは自動変更しません。保存済みの収集拒否とcollectionEnabled=falseが優先されます。アプリの同意・プライバシー表示も確認してください。

// Optional argument in KitsPushConfiguration, after host consent:
notificationEventsEnabled: true

// Forward actual OS callbacks:
kitsPush.handleWillPresent(notification)
kitsPush.handleNotificationResponse(response)

メッセージに{"track_events": true}を追加します。報告にはサーバー発行のkits_delivery_idと正確なバージョンマーカーが必要です。この予約IDを自作しないでください。CLICKEDからRECEIVEDは作られず、プッシュサービスの受理や表示を受信として推定しません。

独自の連携ではawait reportNotificationReceived(payload)またはreportNotificationClicked(payload)を使えます。willPresentはRECEIVED、閉じる操作以外の実際のresponseはCLICKEDを観測します。バックグラウンド受信には、画像なしの通常通知でも受信報告を設定したNotification Service Extensionが必要です。OSの完了処理を独自に遅らせず、SDKの時間制限付き処理を使ってください。

認証拒否（401）などの恒久的な失敗を無制限に再試行しません。記録の報告は通知の配信や分析の完了状態を変更しません。

メッセージ詳細のSDK記録は自動で読み込み、表示中は最大5分間、5秒ごとに更新します。グラフはサーバーに記録が届いた時刻を使うため、端末の実際のクリック時刻とは異なる場合があります。更新したり後から開いたりしても保存済みの時間別記録を確認できます。

画像なし通知のバックグラウンド受信

1. 署名済みのNotification Service Extensionターゲットをアプリに含め、KitsPushNotificationServiceをリンクします。SDKライブラリがターゲットを自動追加することはできません。
2. ダッシュボードで記録収集とiOSバックグラウンド受信収集を両方有効にします。APIではtrack_events=trueとtrack_receipts=trueです。サーバーが通常のAPNs alertにmutable-contentと配信専用の報告トークンを付けます。
3. KitsNotificationServiceExtensionのreceiptConfigurationで、拡張から読める現在の同意を確認します。許可された場合のみKitsNotificationReceiptConfiguration(reportingEnabled: true)、拒否・不明ならnilを返します。アプリSDKの収集拒否は別プロセスの拡張へ自動共有されないため、App Groupなどの共有設定が必要です。

任意：画像拡張機能の追加

1. XcodeでアプリにNotification Service Extensionターゲットを追加します。そのターゲットにはKitsPushNotificationServiceのみを追加し、アプリ用のKitsPushは追加しません。APPLICATION_EXTENSION_API_ONLY=YESと正しい署名・プロビジョニングを維持してください。
2. 以下のヘルパーを保持し、受信と期限切れの両メソッドを渡します。image_urlは通常のメッセージフィールドで送り、Kitsがmutable-contentを設定します。実機で画像と失敗時のテキストを確認してください。

import KitsPushNotificationService
import UserNotifications

final class NotificationService: UNNotificationServiceExtension {
    private let images = KitsNotificationService()
    override func didReceive(_ request: UNNotificationRequest,
        withContentHandler handler: @escaping (UNNotificationContent) -> Void) {
        images.didReceive(request, withContentHandler: handler)
    }
    override func serviceExtensionTimeWillExpire() {
        images.serviceExtensionTimeWillExpire()
    }
}

任意：アプリで登録するiOSボタン

タイトルを翻訳し、category/actionをアプリ内で定義します。他のSDKと競合しないよう、起動時に全体の集合を1回登録してください。ios_categoryは配布済みのidentifierと一致させます。サーバーによる動的なボタン配列はありません。

let category = UNNotificationCategory(identifier: "ORDER_V1", actions: [
    UNNotificationAction(identifier: "VIEW_ORDER", title: "View order", options: .foreground)
], intentIdentifiers: [], options: [])
let actions = try KitsNotificationActions(categories: [category])
let all = try actions.categoriesForRegistration(preserving: otherHostCategories)
UNUserNotificationCenter.current().setNotificationCategories(all)

// In the real response delegate, after forwarding to kitsPush once:
if let event = actions.action(for: response) {
    // Authorize current user and business data before handling event.actionIdentifier.
}

最大32 category、各1–3個のplain actionで、IDの衝突はエラーです。未登録ボタン・別のpayload・通常のタップ・閉じる操作はnilになります。通常のタップは別に処理し、completion handlerを必ず1回呼び出してください。古いSDKや未設定アプリでのボタン表示は保証されません。

SDKのログインとログアウト

• 認証モードはプロジェクト環境ごとに1つで、その環境のすべてのアプリに適用されます。プロジェクト環境の最初のアプリはBASICで始まり、後から追加したアプリはその環境のモードに従います。新SDKの簡単初期化はダッシュボードの設定を自動取得し、アプリ側での再指定は不要です。BASICでは顧客認証callback・JWT発行API・署名鍵は不要です。BASICはexternal IDの所有権を検証しないため、同じ環境のクライアントが別のUIDを名乗り、その通知を受け取る可能性があります。この制約を受け入れる環境で使用してください。VERIFIEDの認証失敗からBASICへ自動切替しません。
• VERIFIEDでは信頼できる顧客バックエンドのJWTが必要です。アプリ起動時にSDKの認証callbackを設定します。顧客バックエンドはセッションと有効なアカウントを検証し、要求されたexternal_idがセッションのUIDと一致することを確認してからcreateIdentityTokenSignerでJWTをローカル署名します。Kitsへのトークン発行HTTPリクエストはなく、既定TTLは300秒です。アプリから受け取ったユーザーIDだけを信用しないでください。
• 顧客環境でgenerateIdentityKeyPairを使い、鍵ペアを一度生成します。Dashboardのプロジェクト設定→SDK接続で、プロジェクト環境にkeyIdとpublicKeyPemだけを登録し、privateKeyPemは顧客バックエンドの秘密情報ストアに保管します。登録した公開鍵は、そのプロジェクト環境のすべてのアプリで共通です。秘密鍵をKitsにアップロードしないでください。新しい公開鍵の登録、署名鍵の切替、古い鍵の失効の順にローテーションします。JWTの署名・検証失敗を旧方式の発行や未検証ログインへ自動迂回しないでください。
• 両モードとも自身のインストールのdeviceTokenでGET /v1/installations/{id}/identityを読み、POST /v1/installations/{id}/identityで紐付けを変更します。VERIFIED LOGINはtokenのみ、BASIC LOGINはexternal_idのみを送信します。LOGOUTではtokenとexternal_idの両方を省略します。SDKがexpected_binding_id、operation_id、永続保存、直列化、再試行を管理します。証明や端末トークンをログに残さないでください。
• SDKは操作のモードを保存し、旧journalはVERIFIEDとして読みます。別モードで再起動した場合は完了状態を先に確認し、異なるモードの未完了LOGINをIDENTITY_AUTH_MODE_CHANGEDで停止します。現在のセッションでloginを再実行すると、ログアウトbarrierを経て選択したモードの新しい操作を作成します。
• 新しいAUTOフローはGET /v1/installations/{id}/identity-policyでbindingと設定revisionを同時に読みます。新しいLOGINのexpected_policy_revisionが変わると409 IDENTITY_REBIND_CONFLICTで再確認します。取得失敗や不正な応答をBASICと推測しません。送信済み操作は先に結果を確認し、VERIFIEDの証明を勝手に省略しません。LOGOUTは設定取得なしで既存のidentity経路を使います。明示的モードと旧journalも互換性を維持します。
• JWTはES256、aud=kits:identity、端末が属するアプリ環境のiss、identity.external_id、整数秒のiat/expを使用します。TTLは1–3600秒で、端末・binding・operationには固定されません。盗まれた場合、有効期間中に別の認証済みインストールで再利用される可能性があり、内容は暗号化されません。HTTPSとCache-Control: no-storeを使い、秘密鍵・JWT・リクエスト本文をログに残さないでください。メッセージごとのJWT発行は不要です。
• 旧方式との互換性としてidentity.createTokenとPOST /v1/identity-tokensは既存のkitid1証明用に残りますが、新しい連携では非推奨です。この旧HTTP経路だけがidentity:writeサーバーキーとインストール・binding・operationの情報を必要とします。ローカルJWT署名にKits APIキーは不要で、messages.createは別のmessages:sendサーバーキーを使用します。
• ローカルキューへの保存は、サーバーでログアウトが完了したことを意味しません。identityStateで確認済みの結果を確認してください。このフローと既存のバックエンドidentify/logoutを同時に実行しないでください。

以下の鍵設定と署名例はVERIFIEDのみで必要です。

import { createIdentityTokenSigner } from '@marco-inc/kits-node';

// VERIFIED backend only: load the private key from your secret store.
const signer = createIdentityTokenSigner({
  appEnvironmentId, keyId, privateKeyPem, ttlSeconds: 300,
});

// In an authenticated handler, after checking the active account:
if (request.external_id !== verifiedUid) throw new Error('Session changed');
const result = signer.sign(verifiedUid); // {token, expires_at}; no HTTP call
// Return only to the authenticated app with Cache-Control: no-store.

アプリ内通知バナーのタップを記録する

Kits.addForegroundListener { event in
    event.preventDefault()
    showInAppBanner(event.title, event.body, event.payload.data) {
        event.recordClick() // Call on MainActor.
        // Keep your existing navigation here.
    }
}

showInAppBannerはアプリ側の表示関数の例です。実際のタップ時だけevent.recordClick()を呼びます。CLICKEDのみを記録し、画面遷移やSDKのタップリスナーを再実行しません。表示だけでタップや推定受信を作りません。メッセージのtrack_events、SDKのnotificationEventsEnabled、収集への同意が必要で、重複・ログアウト・アカウント変更・同意撤回は既存の記録規則に従います。