実装

AudioRecognitionインスタンスの作成

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

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

kotlin

import com.iplateia.sorisdk.SORIAudioRecognizer

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

java

import com.iplateia.sorisdk.SORIAudioRecognizer;

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

TIP

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

WARNING

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

リスナーの実装

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

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

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}")
    }
}

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

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)
    }

    // ...
}

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

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

sori.setListener(this, listener)

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

認識の開始と停止

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

sori.startRecognition(this)

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

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

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

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

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

sori.stopRecognition(this)

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

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

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

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

kotlin

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

java

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

Webhook用メタデータの含有

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

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

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

APIドキュメント

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