LEEEP Android SDK リファレンス

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

サポートしているOS/APIの下限バージョンは Android 5.0 / API 21 です。

LEEEP Android SDKのセットアップを行います。アプリの起動時にこの関数を実行してください（Application.onCreate を推奨）。

パラメータ

• context : アプリの Context。Application でも Activity でも構いません。端末IDの保存に使います。

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

計測に使う端末IDは、アプリ内の自動バックアップされない領域に保存されます。そのため、アプリを再起動しても同じ値が使われ、機種変更でデータを復元しても別の端末に同じIDが引き継がれることはありません。端末IDが変わるのは、アプリのアンインストール時と「データを消去」の時だけです。

SDK 0.10.0で、Context を受け取らない Leeep.setup(websiteId: String) は非推奨になりました。 引き続き動きますが、端末IDが保存されず、アプリを起動するたびに別の端末として計測されます。そのため、アプリを起動し直した後の購入が成果として計測されません。Leeep.setup(context, websiteId) に書き換えてください。なお、警告をエラーとして扱う設定（allWarningsAsErrors）のプロジェクトでは、書き換えるまでビルドが通りません。

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

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

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

パラメータ

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

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

デフォルトは false です。

SDK 0.7.0から、ブログ詳細タグの blogSlug を指定できるオーバーロードを追加しました。既存の2つのオーバーロードも引き続き利用できます。

blogSlug は名前付き引数で指定してください。既存の位置引数や末尾ラムダを使う呼び出しも維持しています。

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

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

SDK 0.7.0では「ソーシャル投稿」「投稿者」「レビュー」「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: ブログ詳細タグで表示する記事のスラッグ。省略時は null です。ブログ詳細を表示するときに指定してください。一覧タグでは指定不要です。

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

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

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

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

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

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

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

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

    • Product : 商品がタップされた場合。 id を用いて商品詳細画面に遷移することを想定しています。IDの種類については、後述の「商品リンクで受け取るID」をご覧ください。

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

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

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

• onScrollRequest: レビュー一覧のページ切替時に、外側のスクロールコンテナをレビュー一覧先頭へ移動するためのコールバック。

  • UIスレッドで呼び出されます。

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

  • onTapLink との取り違えを避けるため、名前付き引数で指定してください。

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

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

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

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

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

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

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

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

SDK 0.7.0から、ブログ詳細タグの blogSlug を指定できるオーバーロードを追加しました。既存の2つのオーバーロードも引き続き利用できます。blogSlug は名前付き引数で指定します。

LEEEPタグのViewを生成します。Viewベース（XMLレイアウト）またはJetpack Composeにおける LazyColumn 内にLEEEPタグを表示するための関数です。 LazyColumn で利用する場合は LazyColumn の外でインスタンスを生成してください。詳しくはクイックスタートをご覧ください。

共通のパラメータは上述の LeeepTagView() と同様です。次のパラメータは makeLeeepTagView() で指定します。

• context: Viewを生成するためのAndroidの Context。

• fileChooserLauncher: WebView内のファイル選択をActivity Result APIで処理するためのlauncher。

makeLeeepTagView で表示する記事を変更する場合は、新しい blogSlug を指定したViewを生成します。

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

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

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

• contentOffsetTop: Webコンテンツ内部における移動先のY座標。Android SDKがWebView内部のスクロールへ使用します。

• hostOffsetTop: LEEEPタグViewの上端から、ホストアプリが表示位置を合わせる点までの距離。現在のAndroid実装では 0.0 ですが、固定値として扱わず、常にプロパティを参照してください。

注文を計測します。

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

パラメータ

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

• products : 注文した商品情報

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

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

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

  • quantity : 販売個数

  • name : 商品名

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

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

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

パラメータ

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

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

LeeepTagView および makeLeeepTagView で生成したタグViewは自動でイベントを送信するため、個別の実装は不要です。

パラメータ

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

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

LeeepTagView および makeLeeepTagView で生成したタグViewは自動でイベントを送信するため、個別の実装は不要です。

パラメータ

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

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

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

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

入力不正時には IllegalArgumentException、未識別状態での同意変更や保存失敗などには IllegalStateException が発生する場合があります。ホスト側で例外を扱い、非同期通信の成否は別途 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 / NOT_DETERMINED / 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処理も無効化してください。

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

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

RemoteMessage.data はそのまま渡せます。配送メタデータを含む値から取り出す場合は、そのメタデータだけを除きます。未知の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・端末認証情報をそのままログに出さないでください。