Implementación

Crear una instancia de AudioRecognition

Al iniciar su aplicación debe crear una instancia de la clase SORIAudioRecognizer. Esta clase se encarga del reconocimiento de audio y proporciona métodos para iniciar y detener el servicio.

Añada el siguiente código al ciclo de vida de su aplicación, por ejemplo, en el método onCreate de la actividad principal.

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

Puede obtener su clave de API y su clave secreta en el panel de SORI API. Consulte la documentación de SORI API para obtener más información.

WARNING

Asegúrese de proteger su clave de API y su clave secreta. NO las incluya directamente en el código fuente de su aplicación. Utilice un método seguro para almacenarlas y recuperarlas, como BuildConfig con local.properties o variables de entorno.

Implementar el listener

La interfaz ISORIListener define los métodos de callback que se invocan cuando se inicia o se detiene el reconocimiento de audio y cuando se recibe el resultado. Puede implementar esta interfaz en su propia clase y sobrescribir los métodos para gestionar los eventos.

En muchos casos, la interfaz de usuario necesita el evento onCampaignFound para actualizar los materiales detectados. Para mayor comodidad, puede utilizar la clase SORIListener como clase base y sobrescribir solo los métodos que necesite.

MySORIListener.kt

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

MySORIListener.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) {
        // Handle the campaign found event
        Log.d("TAG", "Campaign found: " + campaign.getName());
    }
}

También puede extender SORIListener() directamente en su actividad o fragmento. Es recomendable utilizar SORIListener() como clase base para poder interactuar fácilmente con la interfaz de usuario sin pasar el context o la activity al listener.

MainActivity.kt

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

    // ...
}

MainActivity.java

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

    @Override
    public void onCampaignFound(SORICampaign campaign) {
        // Handle the campaign found event
        Toast.makeText(this, "Campaign found: " + campaign.getName(), Toast.LENGTH_SHORT).show();
        adapter.addItem(campaign);
    }

    // ...
}

A continuación, asigne el listener a la instancia de SORIAudioRecognizer.

kotlin

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)

java

SORIListener listener = new SORIListener() {
    @Override
    public void onCampaignFound(SORICampaign campaign) {
        Log.d("TAG", "Campaign found: " + campaign.getName());
    }
};
// or instance of your own listener

sori.setListener(this, listener);

SORIAudioRecognizer configurará un BroadcastReceiver para escuchar los eventos de reconocimiento e invocar los métodos correspondientes de su listener.

Habilitar el reconocimiento de Audio Marker

El reconocimiento de Audio Marker está deshabilitado de forma predeterminada. En el modo predeterminado, el SDK solo realiza reconocimiento mediante huellas de audio. Habilite el reconocimiento de Audio Marker solo cuando su configuración de SORI Console utilice Audio Markers.

import com.iplateia.sorisdk.SORIConfig

sori.setConfig(
    SORIConfig(audiomarker = true)
)

Cuando el reconocimiento de Audio Marker está habilitado, el SDK puede informar de cambios en el estado del marcador independientemente de las coincidencias de campaña:

val listener = object : SORIListener() {
    override fun onPatternMarkerChanged(marker: String?) {
        Log.d("TAG", "Audio Marker: ${marker ?: "none"}")
    }
}

Si se encuentra una campaña en una ventana de reconocimiento que también contiene un marcador, el valor del marcador detectado se adjunta al atributo de la campaña:

override fun onCampaignFound(campaign: SORICampaign) {
    val marker = campaign.trait?.marker
    if (marker != null) {
        Log.d("TAG", "Campaign marker: $marker")
    }
}

En el servidor, SORI Console asigna el marcador detectado a los atributos configurados de Audio Marker para el historial de actividad, las estadísticas, los informes y los webhooks.

TIP

Si su campaña solo debe entregarse cuando se detecte un marcador, configure SORIConfig(audiomarker = true, requirePatternMarkerForCampaign = true).

Iniciar y detener el reconocimiento

Para iniciar el reconocimiento de audio, llame al método startRecognition de la instancia de SORIAudioRecognizer.

kotlin

sori.startRecognition(this)

java

sori.startRecognition(this);

Esto iniciará el servicio de reconocimiento de audio y mostrará una notificación al usuario.

Para personalizar las notificaciones, puede pasar los parámetros title, body e icon al método startRecognition.

kotlin

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

java

sori.startRecognition(
    this,
    "Your APP Name",
    "Finding something special...",
    R.drawable.your_app_icon // optional
);

Si necesita un mayor control sobre la notificación, consulte la sección Personalizar la notificación.

Para detener el reconocimiento de audio, llame al método stopRecognition de la instancia de SORIAudioRecognizer.

kotlin

sori.stopRecognition(this)

java

sori.stopRecognition(this);

Gestionar la acción de la campaña

Cuando se encuentra una campaña, puede implementar el método onCampaignFound en su listener para gestionar la acción. Puede utilizar el objeto SORICampaign que se pasa al método para obtener los detalles de la campaña y ejecutar la acción.

El objeto SORICampaign contiene la propiedad actionUrl, que es una URL que puede utilizar para abrir la campaña en su aplicación o en un navegador web. La propiedad actionUrl es una cadena que contiene la URL de apertura de la campaña. Por lo tanto, puede utilizarla para abrir la campaña en su aplicación o en un navegador web. No obstante, SORI SDK proporciona el práctico método SORIAudioRecognizer.shared().handleActionURL para abrir la campaña en el gestor de URL predeterminado del usuario.

Resulta útil decidir si se abre la campaña en su aplicación o en un navegador web porque actionUrl puede contener un deep link a su aplicación o un enlace web para abrirlo en un navegador.

kotlin

// in your ui
if (campaign.actionUrl != null) {
    SORIAudioRecognizer.shared().handleActionURL(this, campaign.actionUrl)
} else {
    // Handle the case where there is no action URL
}

java

// in your ui
if (campaign.getActionUrl() != null) {
    SORIAudioRecognizer.shared().handleActionURL(this, campaign.getActionUrl());
} else {
    // Handle the case where there is no action URL
}

Incluir metadatos para Webhook

Puede incluir metadatos personalizados en los eventos de webhook enviados a su servidor. Estos metadatos se pueden utilizar para identificar al usuario o dispositivo que activó el evento. Para incluir metadatos, puede utilizar el método setMetadataProvider de la instancia de SORIAudioRecognizer.

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

El método getMetadata debe devolver un mapa de pares clave-valor que se incluirán en el evento de webhook. El método se invocará cada vez que se envíe un evento de webhook, por lo que puede actualizar los metadatos dinámicamente si es necesario.

Documentación de la API

Consulte las Referencias de la API para obtener más información sobre la clase SORIAudioRecognizer y otras clases relacionadas, como SORIListener y SORICampaign.