プレースメントの追加 (レガシー)

Roktパートナー向けに、Android SDKを使用してAndroidアプリ内でオーバーレイまたは埋め込みプレースメントを表示できます。

始める前に

Rokt Android SDKがすでにアプリケーションに統合されていることを確認してください。

オーバーレイプレースメント

SDKを希望するアクティビティ/フラグメントで実行し、適切な顧客属性とプレースメントマッピングを追加します。例のコードでは、onCreateメソッドを使用してプレースメントを起動します。

Roktウィジェットビューは短い遅延の後に表示され、これはRoktプラットフォームを介して設定可能です。SDKはビューがロードおよびアンロードされるときのオプションのコールバックイベントを提供します。

Rokt統合に含める顧客属性を指定できます。利用可能なデータフィールドの詳細は、attributesページで確認できます。より多くの属性を統合したい場合は、以下のサンプルに各新しい属性のコード行を追加できます。

Java

import com.rokt.roktsdk.Rokt

class ConfirmationActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...

        // Include any appropriate consumer attributes
        val attributes = hashMapOf(
                Pair("email", "j.smith@example.com"),
                Pair("firstname", "Jenny"),
                Pair("lastname", "Smith"),
                Pair("mobile", "(323) 867-5309"),
                Pair("postcode", "90210"),
                Pair("country", "US"))

        Rokt.execute("RoktExperience",
            attributes,
            object : Rokt.RoktCallback {
                override fun onUnload(reason: Rokt.UnloadReasons) {
                }
                override fun onLoad() {
                }
                override fun onShouldHideLoadingIndicator() {
                }
                override fun onShouldShowLoadingIndicator() {
                }
            }
        )
        ...
    }

Kotlin

import com.rokt.roktsdk.Rokt;

class ConfirmationActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...

        Map<String,String> attributes = new HashMap<String, String>();

        attributes.put("email", "j.smith@example.com");
        attributes.put("firstname", "Jenny");
        attributes.put("lastname", "Smith");
        attributes.put("mobile", "(323) 867-5309");
        attributes.put("postcode", "90210");
        attributes.put("country", "US");

        Rokt.INSTANCE.execute("RoktExperience",
            attributes,
            new Rokt.RoktCallback() {
                @Override
                public void onLoad() {
                }
                @Override
                public void onUnload(Rokt.UnloadReasons unloadReasons) {
                }
                @Override
                public void onShouldHideLoadingIndicator() {
                }
                @Override
                public void onShouldShowLoadingIndicator() {
                }
            }
        )
        ...
    }
}

オプション機能

機能	目的
Rokt.close()	オーバーレイプレースメントを自動的に閉じるために使用されます。

埋め込みプレースメント

レイアウトXMLファイルの更新

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <com.rokt.roktsdk.Widget
        android:id="@+id/roktWidget"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

注記

Roktの埋め込みプレースメントは、コード内で作成し、レイアウトに動的に含めることもできます。

SDKの実行

SDKを希望するアクティビティ/フラグメントで実行し、適切な顧客属性とプレースメントマッピングを追加します。例のコードでは、onCreateメソッドを使用してプレースメントを起動します。

Roktプレースメントは、Roktプラットフォームを介して設定可能な短い遅延の後に表示されます。

プレースメントの高さをwrap_contentに設定することをお勧めします。これにより、プレースメントがその高さを動的に設定できます。

SDKは、ビューがロードおよびアンロードされるときのオプションのコールバックイベントを提供します。

Rokt統合に含める顧客属性を選択できます。利用可能なデータフィールドの詳細は、attributesページで確認できます。さらに属性を追加したい場合は、以下のサンプルに新しい属性ごとに追加のコード行を追加できます。

Java

import com.rokt.roktsdk.Widget
import com.rokt.roktsdk.Rokt

class ConfirmationActivity : Activity() {

    private val roktCalllback = object : Rokt.RoktCallback {
        override fun onLoad() {
        }

        override fun onShouldShowLoadingIndicator() {
        }

        override fun onShouldHideLoadingIndicator() {
        }

        override fun onUnload(reason: Rokt.UnloadReasons) {
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        ...

        // 適切な消費者属性を含める
        val attributes = hashMapOf(
            Pair("email", "j.smith@example.com"),
            Pair("firstname", "Jenny"),
            Pair("lastname", "Smith"),
            Pair("mobile", "(323) 867-5309"),
            Pair("postcode", "90210"),
            Pair("country", "US")
        )

        // プレースホルダービューとプレースメントロケーション設定をマッピングするウィジェットプレースホルダー
        val widget = findViewById<Widget>(R.id.roktWidget)
        val placeHolders = hashMapOf(
            Pair("RoktEmbedded1", WeakReference(widget))
        )

        Rokt.execute(
            viewName = "RoktExperience",
            attributes = attributes,
            callback = roktCalllback,
            placeholders = placeHolders
        )
        ...
    }
}

Kotlin

import com.rokt.roktsdk.Widget;
import com.rokt.roktsdk.Rokt;

class ConfirmationActivity : Activity() {

    private Rokt.RoktCallback roktCallback = new Rokt.RoktCallback() {
        @Override
        public void onLoad() {
        }

        @Override
        public void onShouldShowLoadingIndicator() {
        }

        @Override
        public void onShouldHideLoadingIndicator() {
        }

        @Override
        public void onUnload(@NotNull Rokt.UnloadReasons unloadReasons) {
        }
    };

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...

        Map<String, String> attributes = new HashMap<String, String>();

        attributes.put("email", "j.smith@example.com");
        attributes.put("firstname", "Jenny");
        attributes.put("lastname", "Smith");
        attributes.put("mobile", "(323) 867-5309");
        attributes.put("postcode", "90210");
        attributes.put("country", "US");

        // Widget placeholder mapping the placeholder view with placement location configuration
        Widget widget = findViewById(R.id.roktWidget);
        Map<String, WeakReference<Widget>> placeHolders = new HashMap<>();
        placeHolders.put("RoktEmbedded1", new WeakReference<>(widget));

        Rokt.INSTANCE.execute("RoktExperience",
                attributes,
                roktCallback,
                placeHolders);
        ...
    }
}

注記

ビュー名 RoktExperience またはプレースホルダー名 RoktEmbedded1 を別の値に更新したい場合は、Rokt の配置が一貫して設定されていることを確認するために、Rokt アカウントマネージャーに連絡してください。

Jetpack Compose コンポーネント

Rokt Android SDK のメジャーバージョン 4 から、RoktLayout コンポーザブルを利用して Rokt レイアウトを追加できます。これにより、Rokt.execute を呼び出す必要がなくなり、Compose を使用したよりモダンな宣言型の統合がサポートされます。

コンポーネントの追加

import com.rokt.roktsdk.RoktLayout

@Composable
fun MainScreen(modifier: Modifier = Modifier) {
    Column(
        modifier = modifier
            .background(Color.LightGray)
            .padding(8.dp),
    ) {
        RoktLayout(
            sdkTriggered = true,
            viewName = "RoktExperience",
            attributes = hashMapOf(
                Pair("email", "j.smith@example.com"),
                Pair("firstname", "Jenny"),
                Pair("lastname", "Smith"),
                Pair("mobile", "(323) 867-5309"),
                Pair("postcode", "90210"),
                Pair("country", "US")
            ),
            location = "RoktEmbedded1", // 埋め込みレイアウトを使用する場合
            onLoad = {},
            onUnload = {},
            onShouldShowLoadingIndicator = {},
            onShouldHideLoadingIndicator = {},
        )
    }
}

注記

RoktLayout コンポーザブルは、埋め込みレイアウトとオーバーレイレイアウトの両方に使用できます。

イベント

SDKは、各ページのイベントをRokt.events APIを通じてストリームとして提供します。SDKユーザーは、Kotlin Flowメカニズムを活用して、SDKによって生成されたイベントを消費できます。

// owner: LifecycleOwner
owner.lifecycleScope.launch {
    owner.lifecycle.repeatOnLifecycle(Lifecycle.State.CREATED) {
        Rokt.events("viewName").collect { roktEvent ->
            Log.d("RoktEvent", "Event received $roktEvent")
        }
    }
}

イベントオブジェクト

イベント	説明	パラメータ
ShowLoadingIndicator	SDKがRoktバックエンドを呼び出す前にトリガーされます
HideLoadingIndicator	SDKがRoktバックエンドから成功または失敗を受信したときにトリガーされます
OfferEngagement	ユーザーがオファーに関与したときにトリガーされます	placementId: String
PositiveEngagement	ユーザーがオファーに対して肯定的に関与したときにトリガーされます	placementId: String
FirstPositiveEngagement	ユーザーが初めてオファーに対して肯定的に関与したときにトリガーされます	placementId: String, fulfillmentAttributes: FulfillmentAttributes
PlacementInteractive	配置がレンダリングされ、対話可能になったときにトリガーされます	placementId: String
PlacementReady	配置が表示可能であるが、まだコンテンツがレンダリングされていないときにトリガーされます	placementId: String
PlacementClosed	ユーザーによって配置が閉じられたときにトリガーされます	placementId: String
PlacementCompleted	オファーの進行が終了し、表示するオファーがもうないときにトリガーされます。 また、キャッシュがヒットしたが、以前に却下されたために取得された配置が表示されない場合にもトリガーされます	placementId: String
PlacementFailure	何らかの失敗により配置を表示できなかった場合、または表示可能な配置がない場合にトリガーされます	placementId: String (オプション)
OpenUrl	ユーザーがパートナーアプリに送信するように設定されたURLを押したときにトリガーされます	placementId: String, url: String

コールバック

Rokt Android SDKは、executeにRokt.RoktCallbackオブジェクトとして渡される以下のコールバックをサポートしています:

onLoad

onLoadコールバックは、プレースメントがロードされてインタラクティブになったときに呼び出されます。このコールバックは引数を提供せず、値を返しません。

onShouldShowLoadingIndicator

onShouldShowLoadingIndicatorは、execute呼び出しが成功した直後、SDKがRoktバックエンドへの呼び出しをトリガーする直前に呼び出されます。プレースメントのロードを待っている間に、ローディングインジケーターの進捗ビューを表示するために使用できます。引数を必要とせず、値を返しません。

注記

このコールバックの動作は、Rokt Android SDKのメジャーバージョン3からメジャーバージョン4の間で変更されました。コールバックが実行される前の1秒の遅延はなくなりました。メジャーバージョン3でこれらのコールバックを使用しており、メジャーバージョン4にアップグレードする場合は、ユーザーエクスペリエンスに影響がないことを確認するために動作をテストしてください。必要に応じて、アプリケーションのニーズに合った遅延動作を作成できます。

onShouldHideLoadingIndicator

onShouldHideLoadingIndicator コールバックは、Rokt バックエンドから成功または失敗のレスポンスを取得したときに SDK によって呼び出されます。これを使用して、プログレスビューやローディングインジケーターをキャンセルすることができます。引数は必要なく、値を返しません。

onUnload

onUnload コールバックは、SDK がプレースメントを閉じるときに呼び出されます。また、execute 呼び出しが失敗した場合にもトリガーされます。引数として Rokt.UnloadReasons を受け取りますが、値を返しません。アンロードの理由は以下の通りです:

値	理由
NO_OFFERS	表示可能なオファーがありません
FINISHED	レンダリングされたプレースメントまたはレイアウトが閉じられました
TIMEOUT	バックエンドからのレスポンス要求時にタイムアウトしました
NETWORK_ERROR	ネットワークエラーが発生しました
NO_WIDGET	返されたプレースメントまたはレイアウトが無効または空です
INIT_FAILED	execute が呼び出される前に初期化リクエストが失敗しました
UNKNOWN_PLACEHOLDER	プレースホルダー文字列の不一致 (4.x.x から利用可能)
UNKNOWN	その他の理由