実装

このガイドはAndroid SDK 5.0.13を対象としています。インストールと更新の手順を参照してください。

AudioRecognitionインスタンスの作成

アプリの開始時に、SORIAudioRecognizerクラスのインスタンスを作成する必要があります。このクラスは音声認識を担当し、サービスを開始および停止するメソッドを提供します。

メインアクティビティのonCreateメソッドなど、アプリのライフサイクルに以下のコードを追加してください。

kotlinjava

kotlin

import com.iplateia.sorisdk.SORIAudioRecognizer

val sori = SORIAudioRecognizer(
    "YOUR_SORI_APP_ID",
    "YOUR_SORI_SECRET_KEY",
)

java

import com.iplateia.sorisdk.SORIAudioRecognizer;

SORIAudioRecognizer sori = new SORIAudioRecognizer(
    "YOUR_SORI_APP_ID",
    "YOUR_SORI_SECRET_KEY"
);

TIP

APIキーとシークレットキーはSORI APIダッシュボードから取得できます。詳細については、SORI APIドキュメントを参照してください。

WARNING

APIキーとシークレットキーを安全に保管してください。アプリのソースコードにハードコードしないでください。代わりに、BuildConfigとlocal.propertiesや環境変数など、安全な方法で保存・取得してください。

リスナーの実装

ISORIListenerインターフェースは、音声認識が開始、停止されたとき、および結果が受信されたときに呼び出されるコールバックメソッドを定義します。このインターフェースを独自のクラスで実装し、メソッドをオーバーライドしてイベントを処理できます。

多くの場合、検出された素材を更新するために、UIでonCampaignFoundイベントが必要です。便宜上、SORIListenerクラスをベースクラスとして使用し、必要なメソッドのみをオーバーライドできます。

MySORIListener.ktMySORIListener.java

kotlin

class MySORIListener : SORIListener() {
    override fun onStateChanged(state: String) {
        Log.d("TAG", "SORI State changed: $state")
    }
    override fun onCampaignFound(campaign: SORICampaign) {
        // キャンペーン発見イベントを処理
        Log.d("TAG", "Campaign found: ${campaign.name}")
    }
}

java

public class MySORIListener extends SORIListener {
    @Override
    public void onStateChanged(String state) {
        Log.d("TAG", "SORI State changed: " + state);
    }
    
    @Override
    public void onCampaignFound(SORICampaign campaign) {
        // キャンペーン発見イベントを処理
        Log.d("TAG", "Campaign found: " + campaign.getName());
    }
}

または、アクティビティやフラグメントでSORIListener()を直接拡張することもできます。SORIListener()をベースクラスとして使用することで、リスナーにcontextやactivityを渡すことなく、UIと簡単にやり取りできるのでよい実践です。

MainActivity.ktMainActivity.java

kotlin

class MyActivity : AppCompatActivity(), SORIListener() {
    private lateinit var adapter: CampaignTimelineAdapter
    // ...

    override fun onCampaignFound(campaign: SORICampaign) {
        // キャンペーン発見イベントを処理
        Toast.makeText(this, "Campaign found: ${campaign.name}", Toast.LENGTH_SHORT).show()
        adapter.addItem(campaign)
    }

    // ...
}

java

public class MainActivity extends AppCompatActivity implements SORIListener {
    private CampaignTimelineAdapter adapter;
    // ...

    @Override
    public void onCampaignFound(SORICampaign campaign) {
        // キャンペーン発見イベントを処理
        Toast.makeText(this, "Campaign found: " + campaign.getName(), Toast.LENGTH_SHORT).show();
        adapter.addItem(campaign);
    }

    // ...
}

次に、SORIAudioRecognizerインスタンスにリスナーを設定します。

kotlinjava

kotlin

val listener = object : SORIListener() {
    override fun onCampaignFound(campaign: SORICampaign) {
        Log.d("TAG", "Campaign found: ${campaign.name}")
    }
}
// または独自のリスナーのインスタンス

sori.setListener(this, listener)

java

SORIListener listener = new SORIListener() {
    @Override
    public void onCampaignFound(SORICampaign campaign) {
        Log.d("TAG", "Campaign found: " + campaign.getName());
    }
};
// または独自のリスナーのインスタンス

sori.setListener(this, listener);

SORIAudioRecognizerは、認識イベントをリッスンし、リスナーで適切なメソッドを呼び出すためにBroadcastReceiverを設定します。

オーディオマーカー認識の有効化

オーディオマーカー認識はデフォルトで無効です。デフォルトモードでは、SDKは音声フィンガープリント認識のみを実行します。SORI Consoleの設定でオーディオマーカーを使用する場合にのみ、オーディオマーカー認識を有効にしてください。

kotlin

import com.iplateia.sorisdk.SORIConfig

sori.setConfig(
    SORIConfig(audiomarker = true)
)

現在のマーカーUIと後続のアクティビティ補完には、SDKが管理する状態とアクティビティ結果APIを使用してください。SDKが失効、マーカーtrait、同一アクティビティの更新を管理します。既存のキャンペーン・検出コールバックとの互換性は維持されます。

TIP

markerが検出された場合にのみキャンペーンを配信する必要がある場合は、SORIConfig(audiomarker = true, requirePatternMarkerForCampaign = true)を設定してください。

順序付き連続アクティビティタイムラインの表示

以下は既存のキャンペーンコールバック向けの説明です。SDKが受理を確認した新しいアクティビティ結果には、オーディオマーカーの状態とアクティビティ結果にある正確なIDによる更新規則を使用してください。この結果は対応する過去のアクティビティも更新できます。

onCampaignFoundは、素材のキャンペーンを最初に配信した後、同じアクティビティに対してmarkerでリファインされたキャンペーンを配信することがあります。最初のコールバックはすぐに表示しつつ、アプリケーションの状態に明示的な現在のセグメントを保持してください。値がある場合は、公開フィールドの campaign.activityId、campaign.materialId、campaign.trait?.markerを使用します。

空でないcampaign.activityIdが現在の行と一致するコールバックだけが、現在の行のキャンペーン表示フィールドを置き換えられます。アクティビティ、キャンペーン、素材IDを使って過去の行を検索しないでください。
古いサーバーがcampaign.activityIdを省略する場合、campaign.materialIdによる fallbackは現在の行だけに適用できます。これはグローバルな識別子ではありません。
現在の行に保存した時刻、位置、その他の初回観測metadataを保持してください。リファイン後のコールバックはキャンペーンとmarkerのデータを更新するものであり、最初の観測を変更するものではありません。
campaign.trait?.markerまたはリファイン後のキャンペーンフィールドを取得した後は、同じセグメントの後続コールバックでmarkerがない場合やデータが不完全な場合も保持します。
別のcampaign.materialIdが観測されたら、新しい現在の行を追加して前のセグメントを閉じます。その古い行に対する遅延リファインは無視してください。

たとえば、A(activity-1) -> A'(activity-1, marker) -> A(activity-1, marker miss)は1つの行のままです。一方、A(activity-1) -> B(activity-2) -> delayed A'(activity-1)ではBが現在のままとなり、履歴上のAは変更されません。

認識の開始と停止

音声認識を開始するには、SORIAudioRecognizerインスタンスのstartRecognitionメソッドを呼び出します。

kotlinjava

kotlin

sori.startRecognition(this)

java

sori.startRecognition(this);

これにより、音声認識サービスが開始され、ユーザーに通知が表示されます。

通知をカスタマイズするには、startRecognitionメソッドにtitle、body、iconパラメータを渡すことができます。

kotlinjava

kotlin

sori.startRecognition(
    this,
    title = "Your APP Name",
    body = "Finding something special...",
    icon = R.drawable.your_app_icon // オプション
)

java

sori.startRecognition(
    this,
    "Your APP Name",
    "Finding something special...",
    R.drawable.your_app_icon // オプション
);

通知をより詳細に制御したい場合は、通知のカスタマイズセクションを参照してください。

音声認識を停止するには、SORIAudioRecognizerインスタンスのstopRecognitionメソッドを呼び出します。

kotlinjava

kotlin

sori.stopRecognition(this)

java

sori.stopRecognition(this);

キャンペーンアクションの処理

キャンペーンが見つかったときは、リスナーでonCampaignFoundメソッドを実装してアクションを処理できます。メソッドに渡されるSORICampaignオブジェクトを使用して、キャンペーンの詳細を取得し、アクションを実行できます。

SORICampaignオブジェクトには、アプリまたはWebブラウザでキャンペーンを開くために使用できるURLであるactionUrlプロパティが含まれています。actionUrlプロパティは、キャンペーンを開くためのURLを含む文字列です。そのため、アプリまたはWebブラウザでキャンペーンを開くために使用できます。ただし、SORI SDKは、ユーザーのデフォルトURLハンドラーでキャンペーンを開くための便利なメソッドSORIAudioRecognizer.shared().handleActionURLを提供しています。

actionUrlにはアプリへのディープリンクまたはWebブラウザで開くWebリンクが含まれている可能性があるため、アプリまたはWebブラウザでキャンペーンを開くかどうかを決定するのに有用です。

kotlinjava

kotlin

// UIで
if (campaign.actionUrl != null) {
    SORIAudioRecognizer.shared().handleActionURL(this, campaign.actionUrl)
} else {
    // アクションURLがない場合を処理
}

java

// UIで
if (campaign.getActionUrl() != null) {
    SORIAudioRecognizer.shared().handleActionURL(this, campaign.getActionUrl());
} else {
    // アクションURLがない場合を処理
}

Webhook用メタデータの含有

サーバーに送信されるWebhookイベントにカスタムメタデータを含めることができます。このメタデータは、イベントをトリガーしたユーザーまたはデバイスを識別するために使用できます。メタデータを含めるには、SORIAudioRecognizerインスタンスでsetMetadataProviderメソッドを使用できます。

kotlinjava

kotlin

sori.setMetadataProvider(
    object : ISORIMetadataProvider {
        override fun getMetadata(): Map<String, String> {
            return mapOf(
                "user_id" to "12345",
                "device_id" to "67890"
            )
        }
    }
)

java

sori.setMetadataProvider(new ISORIMetadataProvider() {
    @Override
    public Map<String, String> getMetadata() {
        Map<String, String> metadata = new HashMap<>();
        metadata.put("user_id", "12345");
        metadata.put("device_id", "67890");
        return metadata;
    }
});

getMetadataメソッドは、Webhookイベントに含まれるキーと値のペアのマップを返す必要があります。このメソッドは、Webhookイベントが送信されるたびに呼び出されるため、必要に応じてメタデータを動的に更新できます。

APIドキュメント

SORIAudioRecognizerクラスおよびSORIListenerやSORICampaignなどの関連クラスの詳細については、APIリファレンスを参照してください。

実装 ​

AudioRecognitionインスタンスの作成 ​

リスナーの実装 ​

オーディオマーカー認識の有効化 ​

順序付き連続アクティビティタイムラインの表示 ​

認識の開始と停止 ​

キャンペーンアクションの処理 ​

Webhook用メタデータの含有 ​

APIドキュメント ​

実装

AudioRecognitionインスタンスの作成

リスナーの実装

オーディオマーカー認識の有効化

順序付き連続アクティビティタイムラインの表示

認識の開始と停止

キャンペーンアクションの処理

Webhook用メタデータの含有

APIドキュメント