Rork Max × Apple TipKit 実装ガイド — オンボーディング離脱を減らすアプリ内ガイダンス設計

// ios/RorkTipKitModule/RorkTipKitModule.swift
import ExpoModulesCore
import TipKit
 
@available(iOS 17.0, *)
public class RorkTipKitModule: Module {
    public func definition() -> ModuleDefinition {
        Name("RorkTipKit")
 
        OnCreate {
            do {
                try Tips.configure([
                    .displayFrequency(.immediate),
                    .datastoreLocation(.applicationDefault)
                ])
            } catch {
                // 失敗してもアプリ全体は止めない。Crashlytics に送る前提のログ
                NSLog("[RorkTipKit] configure failed: \(error.localizedDescription)")
            }
        }
 
        AsyncFunction("donateEvent") { (eventId: String) -> Void in
            await TipEventCenter.shared.donate(eventId)
        }
 
        AsyncFunction("invalidateTip") { (tipId: String) -> Void in
            await TipEventCenter.shared.invalidate(tipId)
        }
 
        Events("onTipAction")
    }
}

// modules/rork-tipkit/index.ts
import { requireOptionalNativeModule, EventEmitter } from "expo-modules-core";
 
type TipActionPayload = {
  tipId: string;
  actionId: string;
};
 
const RorkTipKit = requireOptionalNativeModule("RorkTipKit");
 
const emitter: EventEmitter | null = RorkTipKit
  ? new EventEmitter(RorkTipKit)
  : null;
 
export const tipKit = {
  /**
   * ヒント表示の元になるイベントを記録します。
   * 同じ eventId に対して複数回呼ばれても、TipKit が頻度を制御してくれます。
   */
  async donate(eventId: string): Promise<void> {
    if (!RorkTipKit) return; // iOS 17 未満や Android では no-op
    try {
      await RorkTipKit.donateEvent(eventId);
    } catch (e) {
      console.warn("[tipKit.donate] failed", e);
    }
  },
 
  /**
   * 「もう表示しない」操作を記録します。
   * ユーザーが意図的に閉じた場合に必ず呼んでください。
   */
  async invalidate(tipId: string): Promise<void> {
    if (!RorkTipKit) return;
    try {
      await RorkTipKit.invalidateTip(tipId);
    } catch (e) {
      console.warn("[tipKit.invalidate] failed", e);
    }
  },
 
  /**
   * アクションボタンが押されたときのリスナを登録します。
   * 戻り値の関数を呼ぶと購読解除されます。
   */
  onAction(listener: (payload: TipActionPayload) => void): () => void {
    if (!emitter) return () => {};
    const subscription = emitter.addListener("onTipAction", listener);
    return () => subscription.remove();
  }
};

// app/search.tsx の useEffect 内
useEffect(() => {
  tipKit.donate("search.opened");
 
  const unsubscribe = tipKit.onAction(({ tipId, actionId }) => {
    if (tipId === "filter.tip" && actionId === "learn-more") {
      router.push("/help/filter");
    }
  });
 
  return unsubscribe;
}, []);

// ios/RorkTipKitModule/Tips/FilterTip.swift
import TipKit
 
@available(iOS 17.0, *)
struct FilterTip: Tip {
    static let searchOpenedEvent = Event(id: "search.opened")
    static let filterUsedEvent = Event(id: "filter.used")
 
    var id: String { "filter.tip" }
 
    var title: Text { Text("もっと絞り込めます") }
    var message: Text? {
        Text("検索結果が多いときは、上部のフィルターで一気に絞り込めます。")
    }
    var image: Image? { Image(systemName: "line.3.horizontal.decrease.circle") }
 
    var rules: [Rule] {
        // 検索画面を3回以上開いている
        #Rule(Self.searchOpenedEvent) { $0.donations.count >= 3 }
        // まだフィルターを使っていない
        #Rule(Self.filterUsedEvent) { $0.donations.count == 0 }
        // 過去24時間以内にも検索画面を開いている（古い使い方の人を除外）
        #Rule(Self.searchOpenedEvent) {
            $0.donations.donatedWithin(.days(1)).count >= 1
        }
    }
}

// SwiftUI 側のカスタムタブバー内
import SwiftUI
import TipKit
 
@available(iOS 17.0, *)
struct FilterButton: View {
    private let tip = FilterTip()
 
    var body: some View {
        Button(action: openFilter) {
            Image(systemName: "line.3.horizontal.decrease.circle")
                .font(.title2)
        }
        .popoverTip(tip, arrowEdge: .top) { action in
            // アクションボタンがタップされたとき
            // 親モジュールに転送して JS 側に通知
            RorkTipKitModule.dispatch(
                tipId: tip.id,
                actionId: action.id
            )
            tip.invalidate(reason: .actionPerformed)
        }
    }
 
    private func openFilter() {
        // donate しておくと「フィルターを既に使ったユーザー」として
        // 別のヒントの判定に活用できる
        Task { await TipEventCenter.shared.donate(FilterTip.filterUsedEvent.id) }
    }
}

// scripts/sync-tipkit-strings.mjs（Cloudflare CI でも動く ESM）
import { readFile, writeFile, mkdir } from "node:fs/promises";
import { join } from "node:path";
 
const LOCALES = ["ja", "en", "zh-Hans", "ko"];
 
for (const locale of LOCALES) {
  try {
    const json = JSON.parse(
      await readFile(join("messages", `${locale}.json`), "utf8")
    );
    const tipKeys = Object.entries(json.tipkit ?? {});
    if (tipKeys.length === 0) {
      console.warn(`[sync-tipkit] no keys for ${locale}, skipping`);
      continue;
    }
    const lines = tipKeys
      .map(([k, v]) => `"tipkit.${k}" = ${JSON.stringify(v)};`)
      .join("\n");
    const dir = join("ios", "RorkTipKitModule", "Resources", `${locale}.lproj`);
    await mkdir(dir, { recursive: true });
    await writeFile(join(dir, "Tips.strings"), lines + "\n", "utf8");
    console.log(`[sync-tipkit] wrote ${tipKeys.length} keys → ${locale}`);
  } catch (e) {
    console.error(`[sync-tipkit] failed for ${locale}:`, e);
    process.exitCode = 1;
  }
}

try Tips.configure([
    .displayFrequency(.immediate),
    .datastoreLocation(
        .groupContainer(identifier: "group.net.rorklab.example.tips")
    ),
    .cloudKitContainer(.namedDefault("iCloud.net.rorklab.example"))
])

import * as Analytics from "expo-firebase-analytics";
 
tipKit.onAction(({ tipId, actionId }) => {
  Analytics.logEvent("tip_action", {
    tip_id: tipId,
    action_id: actionId,
    // 「ヒント表示後 N 秒以内に該当機能を使ったか」も別途取る
  });
});

@available(iOS 17.0, *)
struct FilterTip: Tip {
    static var copyVariant: CopyVariant = .control
 
    var id: String { "filter.tip.\(Self.copyVariant.rawValue)" }
 
    var title: Text { Text(Self.copyVariant.titleKey) }
    var message: Text? { Text(Self.copyVariant.messageKey) }
    var image: Image? { Image(systemName: "line.3.horizontal.decrease.circle") }
 
    var rules: [Rule] {
        // 全バリアントで共通のルール。差分は文言のみ
        #Rule(Self.searchOpenedEvent) { $0.donations.count >= 3 }
        #Rule(Self.filterUsedEvent) { $0.donations.count == 0 }
    }
}
 
enum CopyVariant: String, CaseIterable {
    case control, friendly, urgent
    var titleKey: LocalizedStringResource { "tipkit.filter.title.\(rawValue)" }
    var messageKey: LocalizedStringResource { "tipkit.filter.message.\(rawValue)" }
}

// SwiftUI の List 内
if let tip = ResultsHelpTip.current {
    TipView(tip)
        .padding(.horizontal)
}