การนำไปใช้

สร้าง instance ของ AudioRecognition

เมื่อเริ่มต้นแอป คุณต้องสร้าง instance ของคลาส SORIAudioRecognizer คลาสนี้ทำหน้าที่รู้จำเสียงและ มี methods สำหรับเริ่มและหยุด service

เพิ่มโค้ดต่อไปนี้ลงใน lifecycle ของแอป เช่น ใน method onCreate ของ main activity

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 key และ secret key ได้จาก SORI API dashboard โปรดดูข้อมูลเพิ่มเติมที่ เอกสาร SORI API

WARNING

โปรดเก็บ API key และ secret key ให้ปลอดภัย อย่า hardcode ค่าเหล่านี้ใน source code ของแอป ให้ใช้วิธีที่ปลอดภัยในการจัดเก็บ และดึงข้อมูลแทน เช่น ใช้ BuildConfig ร่วมกับ local.properties หรือ environment variables

นำ listener ไปใช้

interface ISORIListener กำหนด callback methods ที่จะถูกเรียกเมื่อ การรู้จำเสียงเริ่มต้น หยุด และเมื่อได้รับผลลัพธ์ คุณสามารถ นำ interface นี้ไปใช้ในคลาสของคุณเองและ override methods เพื่อ จัดการ events ได้

ในหลายกรณี UI ต้องใช้ event onCampaignFound เพื่ออัปเดต สื่อ (Material) ที่ตรวจพบ เพื่อความสะดวก คุณสามารถใช้คลาส SORIListener เป็น base class และ override เฉพาะ methods ที่ต้องการ

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

หรือ extend SORIListener() โดยตรงใน activity หรือ fragment ก็ได้ แนวทางที่ดีคือใช้ SORIListener() เป็น base class เพื่อให้คุณ โต้ตอบกับ UI ได้อย่างง่ายดายโดยไม่ต้องส่ง context หรือ activity ไปยัง 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);
    }

    // ...
}

จากนั้นกำหนด listener ให้กับ instance ของ 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 จะตั้งค่า BroadcastReceiver เพื่อรับฟัง events การรู้จำและเรียก methods ที่เหมาะสมใน listener

เปิดใช้งานการรู้จำ Audio Marker

การรู้จำ Audio Marker ถูกปิดไว้โดยค่าเริ่มต้น ในโหมดเริ่มต้น SDK จะทำเฉพาะการรู้จำ audio fingerprint ให้เปิดการรู้จำ Audio Marker เฉพาะเมื่อการตั้งค่า SORI Console ใช้ Audio Markers

import com.iplateia.sorisdk.SORIConfig

sori.setConfig(
    SORIConfig(audiomarker = true)
)

เมื่อเปิดใช้งานการรู้จำ Audio Marker แล้ว SDK สามารถรายงานการเปลี่ยนแปลง สถานะมาร์กเกอร์โดยแยกจากการตรวจพบแคมเปญ:

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

หากพบแคมเปญจากช่วงการรู้จำที่มีมาร์กเกอร์อยู่ด้วย ค่ามาร์กเกอร์ที่ตรวจพบจะถูกแนบกับ trait ของแคมเปญ:

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

ในฝั่งเซิร์ฟเวอร์นั้น SORI Console จะจับคู่มาร์กเกอร์ที่ตรวจพบกับแอตทริบิวต์ ที่กำหนดค่าไว้ของ Audio Marker เพื่อใช้กับประวัติกิจกรรม สถิติ รายงาน และ Webhook

TIP

หากต้องการส่งแคมเปญเฉพาะเมื่อตรวจพบมาร์กเกอร์ ให้กำหนดค่า SORIConfig(audiomarker = true, requirePatternMarkerForCampaign = true)

เริ่มและหยุดการรู้จำ

หากต้องการเริ่มการรู้จำเสียง ให้เรียก method startRecognition จาก instance ของ SORIAudioRecognizer

kotlin

sori.startRecognition(this)

java

sori.startRecognition(this);

การดำเนินการนี้จะเริ่ม service การรู้จำเสียงและแสดงการแจ้งเตือนแก่ ผู้ใช้

หากต้องการปรับแต่งการแจ้งเตือน คุณสามารถส่ง parameters title, body และ icon ไปยัง method 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
);

หากต้องการควบคุมการแจ้งเตือนเพิ่มเติม โปรดดูหัวข้อ การปรับแต่งการแจ้งเตือน

หากต้องการหยุดการรู้จำเสียง ให้เรียก method stopRecognition จาก instance ของ SORIAudioRecognizer

kotlin

sori.stopRecognition(this)

java

sori.stopRecognition(this);

จัดการ action ของแคมเปญ

เมื่อพบแคมเปญ คุณสามารถนำ method onCampaignFound ไปใช้ใน listener เพื่อจัดการ action โดยใช้ object SORICampaign ที่ส่งมาให้ method เพื่อดูรายละเอียดแคมเปญและดำเนิน action

object SORICampaign มี property actionUrl ซึ่งเป็น URL ที่ ใช้เปิดแคมเปญในแอปหรือ web browser ได้ property actionUrl เป็น string ที่มี URL สำหรับเปิดแคมเปญ ดังนั้น คุณจึงใช้เปิดแคมเปญในแอปหรือ web browser ได้ อย่างไรก็ตาม SORI SDK มี method ที่สะดวกคือ SORIAudioRecognizer.shared().handleActionURL สำหรับเปิดแคมเปญด้วย ตัวจัดการ URL เริ่มต้นของผู้ใช้

คุณควรตัดสินใจว่าจะเปิดแคมเปญในแอปหรือ web browser เนื่องจาก actionUrl อาจมี deep link ไปยังแอปหรือ web link สำหรับเปิดใน web browser

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
}

เพิ่ม metadata สำหรับ Webhook

คุณสามารถเพิ่ม metadata ที่กำหนดเองใน Webhook events ที่ส่งไปยังเซิร์ฟเวอร์ได้ metadata นี้ใช้ระบุผู้ใช้หรืออุปกรณ์ที่ทริกเกอร์ event หากต้องการ เพิ่ม metadata ให้ใช้ method setMetadataProvider จาก instance ของ 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;
    }
});

method getMetadata ควรคืนค่า map ของคู่ key-value ที่จะ รวมอยู่ใน Webhook event โดยจะเรียก method นี้ทุกครั้งที่ส่ง Webhook event คุณจึงอัปเดต metadata แบบ dynamic ได้หากจำเป็น

เอกสาร API

โปรดดูรายละเอียดเพิ่มเติมเกี่ยวกับคลาส SORIAudioRecognizer และคลาสอื่นที่เกี่ยวข้อง เช่น SORIListener และ SORICampaign ได้ที่ เอกสารอ้างอิง API