LEEEP iOS SDK リファレンス

※ 導入手順はLEEEP iOS SDKクイックスタートをご覧ください。

サポートしているOSの下限バージョンは iOS 16.0 です。

LEEEP iOS SDKのセットアップを行います。アプリの起動時にこの関数を実行してください。

パラメータ

• websiteId : LEEEP上で管理しているウェブサイトのID（LEEEP管理画面でご確認ください）

ユーザーIDをセットすることで、LEEEPのイベント計測時に同一のユーザーとして扱われます。

アプリ上で会員ログイン時にユーザーIDをこの関数に与え、ログアウト時に nil をこの関数に与えてください。

Pushを利用する場合は、同じ会員IDを LeeepPushClient.identify にも渡します。ログアウト時は LeeepPushClient.logout も呼びます。詳しくは本記事の「プッシュ通知」をご覧ください。

パラメータ

• userId : あなたのアプリ/サービス上で管理している、ユーザーを一意に識別する文字列

true にすると LeeepTagView の初期化時やイベント計測時に正常系のログを出力します（異常系のログは showLog = false の状態でも出力されます）。

デフォルトは false です。

LEEEPタグのviewを生成します。ScrollView の中で呼び出してください。

内部的にはweb向けのLEEEPタグをWebViewで表示し、ページ遷移の処理を onTapLink に引き継いでいます。

SDK 0.11.0では「ソーシャル投稿」「投稿者」「レビュー」「UGC（リスト / UGC投稿詳細ページ）」「ブログ一覧」「ブログ詳細」のタグを表示できます。

パラメータ

• tagId : LEEEPタグのID（LEEEP管理画面でご確認ください）

• productId : あなたのアプリ/サービス上で管理している商品ID

  • 商品詳細ページなどで、その商品が紐づいたコンテンツのみを表示したい場合などに使います

  • Shopifyをお使いの場合、LeeepTagView の生成時のみ cartProductId として商品IDを与える必要があります。詳しくは担当者にお問い合わせください

• cartProductId: カートシステム上の商品ID。利用要否は担当者へお問い合わせください。

• brandCode: 表示対象を絞り込むブランドコード。

• postId : LEEEP上で管理している投稿ID

  • ソーシャル投稿詳細ページタグまたはUGC投稿詳細ページタグを表示する際に与えてください。

  • UGC投稿詳細ページタグにはUGC投稿IDを与えてください。

• staffId : LEEEP上で管理している投稿者ID

  • 投稿者詳細ページタグを表示する際に与えてください

• blogSlug: ブログ詳細タグで表示する記事のスラッグ。省略時は nil です。ブログ詳細を表示するときに指定してください。一覧タグでは指定不要です。

  • スラッグはURL全体ではなく、記事を識別する文字列です。URLエンコード前の値を指定します。ブログ記事の指定には postId を使用しません。

  • SwiftUIで同じ画面の表示記事を変更する場合は、.id(slug) などを使ってタグViewを再生成してください。UIKitでは新しい blogSlug を指定したタグViewを生成します。

• onTapLink : タグ内のリンクがクリックされたときのコールバック

  • 引数の LeeepLinkHandlerParam により、以下のパターンで分岐させることができます

    • .post : 投稿がタップされた場合。id を用いてソーシャル投稿詳細ページタグを表示することを想定しています

    • .ugc : UGC投稿がタップされた場合。id を用いてUGC投稿詳細ページタグを表示することを想定しています。

      • UGCリストタグの「ページ遷移モード」がONで、ウェブサイトにUGC投稿詳細ページの設定がある場合に発火します。

      • 「ページ遷移モード」がOFFの場合は従来どおりポップアップ表示となり、.ugc は発生しません。

    • .staff : 投稿者がタップされた場合。id を用いて投稿者詳細ページタグを表示することを想定しています

    • .product : 商品がタップされた場合。id を用いて商品詳細画面に遷移することを想定しています。IDの種類は下記「商品リンクで受け取るID」を参照してください。

    • .reviewForm : レビューリストタグにおいて「レビューを書く」のボタンがタップされた場合。productId を用いてレビューフォーム画面に遷移することを想定しています

      • case reviewForm(productId: String?, cartProductId: String?, url: URL)

    • .blog : ブログ記事へのリンクがタップされた場合。受け取った slug を使ってブログ詳細画面へ遷移し、詳細タグの blogSlug に渡します。

    • .other : その他のリンクがタップされた場合。url を用いてブラウザを開くか、または何もしないことを想定しています

• onScrollRequest: Webコンテンツからホストアプリへ送られるスクロール要求のコールバック。レビュー一覧のページ切替時に、外側のスクロールコンテナをレビュー一覧先頭へ移動するために使用します。

  • コールバックはメインスレッドで呼び出されます。

  • 設定は任意です。省略した既存実装との互換性は維持されます。

  • LeeepTagViewUIKit.onScrollRequest へ後から設定することもできますが、nil と非nilを切り替えた場合はタグが再読み込みされるため、initializerでの指定を推奨します。

v0.8.0で LeeepLinkHandlerParam に .ugc が追加されました。 default （または @unknown default ）を書かずに全ケースを列挙する switch を実装している場合、v0.8.0への更新時にコンパイルエラーとなりますので、 .ugc の分岐を追加してください。

ブログ記事へのリンクをタップしたときの通知です。slug は記事のスラッグ、url はタップしたリンクのURLです。アプリ側でブログ詳細画面へ遷移し、受け取った slug を LeeepTagView または LeeepTagViewUIKit の blogSlug に渡してください。

LEEEP管理画面のブログ詳細ページ設定と一致したリンクを判定します。たとえば、次のいずれかの形式を設定できます。

設定が未登録、またはブログリンクとして判定できないリンクは .other などの既存の通知種別で処理されます。通常のWebサイトで開くブログ詳細URLに合わせて設定してください。

SDK 0.11.0から .blog が追加されています。全ケースを列挙した switch は更新が必要です。default / @unknown default で受けるだけではブログ詳細画面へ遷移しないため、ブログをアプリ内で表示する場合は .blog の処理を追加してください。ブログ以外の通知処理も引き続き実装します。

既存のタグ生成コードは blogSlug を省略して利用できます。SDKを更新したアプリは再ビルドしてください。

ソーシャル投稿詳細・ブログ詳細の商品リンクをタップしたとき、.product(id:url:) の id には、LEEEP管理画面の「アプリSDK連携設定 > SDKに渡す商品ID」で選んだ種類のIDが入ります。

アプリの商品詳細画面が受け付けるIDに合わせて設定します。Appifyなどカート商品IDで商品を識別するアプリでは、カート商品IDを使用してください。新規設定時は使用する種類を明示してください。未設定の既存サイトには互換動作があるため、現在の設定は担当者へお問い合わせください。

この設定は、リンクをタップしたときに受け取るIDの設定です。タグ表示時の絞り込みに使う productId / cartProductId や、注文・商品閲覧イベントへ渡すIDは、それぞれの連携仕様に従ってください。Shopifyの商品同期で「商品IDとして利用する情報を選択」する設定とも別の項目です。

LeeepTagViewUIKit には公開された関数として refreshLayout を用意しています。

タグViewが配置された画面の構造や動作によっては、タグviewの描画が適切に行われない場合があるかもしれません。その際はこちらの関数を実行して再描画を行ってください。

• tagId: スクロール要求を送ったLEEEPタグのID。

• reason: スクロールが必要になった理由。現在は .reviewPagination です。

• target: 移動先。現在は .reviewListTop です。

• contentOffsetTop: Webコンテンツ内部における移動先のY座標。

• hostOffsetTop: LeeepTagView の上端から、ホストアプリが表示位置を合わせる点までの距離。外側のスクロール計算にはこちらを使用してください。

SwiftUIの ScrollView を利用する場合も、onScrollRequest で受け取った hostOffsetTop を、アプリ側レイアウトの座標へ変換して外側のコンテナを移動します。iOS 16の ScrollViewReader だけでは任意のY座標を直接指定できないため、画面構成に応じてスクロール対象のマーカーを用意するか、正確な座標制御が必要な場合は UIScrollView をラップしてください。

注文を計測します。

webの購入完了ページで既に ParteTracking.order() を実装済みで、アプリからの注文でもwebの購入完了ページを表示する場合、アプリ側の実装は不要です。詳しくはお問い合わせください。

パラメータ

• orderId : あなたのアプリ/サービス上で管理している注文ID

• products : 注文した商品情報

  • productId : あなたのアプリ/サービス上で管理している商品ID

  • skuCode : あなたのアプリ/サービス上で管理しているSKUコード。SKUコードがない商品の場合 "-" を与えてください

  • salesPrice : 販売価格。定価ではなく割引等が適用された販売価格を与えてください

  • quantity : 販売個数

  • name : 商品名

• discountAmount : 注文全体に対する割引金額。個々の商品に対する割引は products[].salesPrice に与えてください

ページビューを計測します。

商品のビューを計測します。商品詳細画面に遷移したときにこの関数を実行してください。

パラメータ

• productId : あなたのアプリ/サービス上で管理している商品ID

LEEEPタグのビューを計測します。

LeeepTagView LeeepTagViewUIKit は自動で viewTag を発火するため実装不要です。

パラメータ

• tagId : LEEEPタグのID（LEEEP管理画面でご確認ください）

LEEEPの投稿のビューを計測します。

LeeepTagView LeeepTagViewUIKit は自動で viewPost を発火するため実装不要です。

パラメータ

• postId : LEEEP上で管理している投稿ID

Pushは任意の追加連携です。既存の Leeep.setup() やタグ表示だけではPush登録は始まりません。LeeepPushClient が端末登録・会員紐付け・同意・権限のサーバー同期を担当し、LeeepPushPayload が通知dataを検証します。Firebaseによる通知受信と、登録済みFID・OS通知権限の取得は、アプリ側で準備済みとします。ここではLEEEP SDKへの入力・同期・通知データの扱いを説明します。

IDは説明用です。同じwebsite・Pushアプリ・API接続先について、クライアントを1つ保持してください。

検証用と本番用のアプリは、必要に応じて別のPushアプリID・Firebaseアプリとして登録します。

Swiftの throws が付くAPIは do / catch で扱います。LeeepPushClientError は invalidInput / storageFailure / invalidResponse / networkFailure です。非同期通信の成否は別途 LeeepPushStatus で確認します。

2つのAPIには同じ外部会員IDを渡してください。PushのIDを指定するだけでは既存タグのユーザーIDは更新されません。フォローも同じ会員IDで行う必要があります。

userId はUTF-8で1〜255バイト、空白だけの値は不可です。SDKは受け取った文字列の前後空白除去やUnicode正規化を行いません。アプリでIDの表記を統一してください。installation ID・Firebase FID・端末固有IDを外部会員IDの代わりに使いません。

会員IDの原文はメモリ上だけに保持します。アプリ再起動後は、ログイン状態を復元して再び identify を呼びます。ホストアプリのログイン機能は別途必要ですが、LEEEP Push向けのJWT発行・更新処理は不要です。

• kind は "fcm_fid" のみです。

• value はFCMに登録済みのFirebase Installation IDです。形式は [cdef][A-Za-z0-9_-]{21}。FCMトークン・APNsトークンは受理しません。

• permission は LeeepPushPermission の unknown / notDetermined / denied / granted / provisional です。配信可能な権限は granted です。

• update は非同期処理を開始する前に取得します。省略すると同期呼び出し時に新しいチケットを作るため、非同期処理の結果を反映するときは必ず開始時の値を渡してください。

チケットは会員の切替・ログアウトや、より新しい宛先更新の開始で古くなります。古いチケットの結果は反映されません。完了コールバック内でチケットを取り直すと、この保護が働かないため避けてください。

SDKへ渡すFIDは、アプリ側でFCMへの登録成功を確認した現在の値を使用します。古いFIDやログアウト前の結果を使い回さず、FID・OS権限に変化があったら同期します。onForeground() は保留中の同期を再試行するAPIであり、OS権限の取得はアプリ側で行います。

以下はそれぞれの操作イベントで呼ぶ例です。連続して全部実行するコードではありません。

通知同意は会員・Pushアプリ単位です。同じ会員・同じアプリの別端末にも関係する設定で、初期値 unknown は配信対象になりません。利用者が明示的にONを選択したときにだけ opted_in にします。OS権限を許可しただけではLEEEPの同意はONになりません。

logout() はその端末の会員紐付けを解除します。Firebase自体の登録解除や、他サービスのログアウトは行いません。端末認証情報を手動で消す必要はありません。ホストの会員切替・ログアウトでは、保留中のFirebase処理も無効化してください。

nil の場合はLEEEPの通知として扱いません。解析できた場合は payload.target から対象のIDを取り出します。

LeeepPushPayload は scope・notificationId・deliveryId・target を公開します。target はコーデ（sourceContentId, ugcId）またはブログ（sourceContentId, ugcId, slug）です。通知のタイトル・本文や遷移URLはこの型には含まれません。解析結果はデータの形式と宛先を確認したもので、記事の現在の公開状態は含みません。

iOSでは userInfo 全体ではなく、APNs/FCMの配送情報を除いたdata部分を渡します。LEEEPが認めるキーだけを選び直して未知のdataキーを消すと、SDKが不正な入力を検出できなくなるため、data自体の項目は保持してください。

LeeepPushPayload.parse が受け取るのは、次のキーだけで構成された 文字列のdataマップ です。通知のタイトル・本文と、アプリが解析するdataは別です。schema_version は文字列の "2" を使用します。

上記IDは説明用です。website_id・app_id・source_content_id・ugc_id は先頭が0でない1〜19桁の数字文字列です。notification_id・delivery_id は1〜128文字で、先頭は英数字、残りは英数字・.・_・:・- を使用できます。blog_slug は1〜255 Unicodeコードポイントです。

遷移URLを指定するフィールドはありません。未知の追加キー、数値型などの文字列以外、旧schema、不正値、別website・別アプリ宛ての通知は解析に失敗します。アプリの設定から expectedScope を作ってください。通知自身の値で期待値を作ると、宛先の照合になりません。

ブログ通知と、アプリ側で取得済みの記事情報が一致するかを確認する補助APIです。payload.matchesPublicBlogDetail(websiteId:slug:ugcId:isPublic:) に次の値を渡します。

ブログ通知のwebsite・slug・UGC IDと一致し、isPublic がtrueの場合にtrueを返します。コーデ通知や不一致の場合はfalseです。このAPIは渡された値を照合するもので、記事の取得や画面表示はアプリ側で行います。

更新番号や操作IDはSDKが管理します。ホストから直接書き換える必要はありません。状態にはinstallation key、会員IDの原文、Firebaseの宛先は含まれません。

bound=true、consent="opted_in"、osPermission="granted"、pending=false、error が空なら、受信準備の登録・同期を確認できます。これは通知の送信・到着・画面表示を保証する条件ではありません。対象スタッフのフォロー、LEEEP側の配信設定、公開投稿、FCM/APNs/OS側の配送状態も関係します。

retry() / onForeground() は保留中の同期を再試行します。Firebaseの再登録、OS権限の再取得、アプリのログイン復元はホスト側で行います。メソッドの呼び出し直後に pending=false になるとは限りません。

通知OFFやログアウトのサーバー反映も通信を伴います。オフライン時は保留されるため、その場で配信が停止したと判断せず同期結果を確認してください。通知本文・会員ID・FID・端末認証情報をそのままログに出さないでください。