Implementation

Create AudioRecognition instance

At the beginning of your app, you need to create an instance of SORIAudioRecognizer class. This class is responsible for audio recognition and provides methods to start and stop service.

Please add the following code to your app's lifecycle, for example in onCreate method of your main activity.

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

You can get your API key and secret key from the SORI API dashboard. Please refer to the SORI API documentation for more information.

WARNING

Please make sure to keep your API key and secret key secure. DO NOT hardcode them in your app's source code. Instead, use a secure method to store and retrieve them, such as BuildConfig with local.properties or environment variables.

Implement your listener

ISORIListener interface defines the callback methods that will be called when the audio recognition is started, stopped, and when the result is received. You can implement this interface in your own class and override the methods to handle the events.

In many cases, the onCampaignFound event is needed by UI to update the detected materials. For convinience, you can use the SORIListener class as a base class and override only the methods you need.

class MySORIListener : SORIListener() {
    override fun onStateChanged(state: String) {
        Log.d("TAG", "SORI State changed: $state")
    }
    override fun onCampaignFound(campaign: SORICampaign) {
        // Handle the campaign found event
        Log.d("TAG", "Campaign found: ${campaign.name}")
    }
}

Or simply extend the SORIListener() directly in your activity or fragment. It is a good practice to use SORIListener() as a base class, so you can easily interact with your UI without passing the context or activity to the listener.

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

    override fun onCampaignFound(campaign: SORICampaign) {
        // Handle the campaign found event
        Toast.makeText(this, "Campaign found: ${campaign.name}", Toast.LENGTH_SHORT).show()
        adapter.addItem(campaign)
    }

    // ...
}

Then, set the listener to the SORIAudioRecognizer instance.

val listener = object : SORIListener() {
    override fun onCampaignFound(campaign: SORICampaign) {
        Log.d("TAG", "Campaign found: ${campaign.name}")
    }
}
// or instance of your own listener

sori.setListener(this, listener)

SORIAudioRecognizer will setup a BroadcastReceiver to listen for the recognition events and call the appropriate methods on your listener.

Start and stop recognition

To start the audio recognition, call the startRecognition method on the SORIAudioRecognizer instance.

sori.startRecognition(this)

This will start the audio recognition service and show a notification to the user.

To customize your notifications, you can pass title, body, and icon parameters to the startRecognition method.

sori.startRecognition(
    this,
    title = "Your APP Name",
    body = "Finding something special...",
    icon = R.drawable.your_app_icon // optional
)

To stop the audio recognition, call the stopRecognition method on the SORIAudioRecognizer instance.

sori.stopRecognition(this)

Including metadata for Webhook

You can include custom metadata in the webhook events sent to your server. This metadata can be used to identify the user or device that triggered the event. To include metadata, you can use the setMetadataProvider method on the SORIAudioRecognizer instance.

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

getMetadata method should return a map of key-value pairs that will be included in the webhook event. The method will be called every time a webhook event is sent, so you can update the metadata dynamically if needed.