การนำไปใช้

คู่มือนี้ใช้ Android SDK 5.1.0 ดูขั้นตอนการติดตั้งและอัปเดต

สร้าง 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)
)

สำหรับ UI มาร์กเกอร์ปัจจุบันและการเสริมข้อมูลกิจกรรมภายหลัง ให้ใช้ API สถานะและผลลัพธ์กิจกรรมที่ SDK จัดการ SDK จัดการการหมดอายุ trait ของมาร์กเกอร์ และการอัปเดตกิจกรรมเดิม โดยยังรองรับ callback ของแคมเปญและการค้นพบเดิม

TIP

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

แสดง timeline ของกิจกรรมต่อเนื่องตามลำดับ

คำแนะนำต่อไปนี้ใช้กับ callback แคมเปญเดิม สำหรับผลลัพธ์กิจกรรมใหม่ที่ SDK ยืนยันแล้ว ให้ใช้กฎอัปเดตด้วย ID ที่ตรงกันใน สถานะ Audio Marker และผลลัพธ์กิจกรรม ซึ่งสามารถอัปเดตกิจกรรมย้อนหลังที่ตรงกันได้

onCampaignFound อาจส่งแคมเปญของสื่อมาก่อน แล้วจึงส่งแคมเปญที่ปรับละเอียดด้วย marker สำหรับกิจกรรมเดียวกัน ให้แสดง callback แรกทันที แต่เก็บ segment ปัจจุบัน ไว้อย่างชัดเจน ใน state ของแอปพลิเคชัน และใช้ฟิลด์สาธารณะ campaign.activityId, campaign.materialId และ campaign.trait?.marker เมื่อมีค่า

• callback ที่มี campaign.activityId ไม่ว่างและตรงกับแถวปัจจุบันเท่านั้นที่แทนที่ฟิลด์ การแสดงผลของแคมเปญในแถวนั้นได้ อย่าค้นหาแถวเก่าด้วย ID ของกิจกรรม แคมเปญ หรือสื่อ
• หากเซิร์ฟเวอร์รุ่นเก่าไม่มี campaign.activityId ให้ใช้ campaign.materialId เป็น fallback ได้เฉพาะกับแถวปัจจุบันเท่านั้น ค่านี้ไม่ใช่ identity แบบ global
• คงเวลา ตำแหน่ง และ metadata อื่นของการตรวจพบครั้งแรกที่เก็บไว้สำหรับแถวปัจจุบัน callback ที่ปรับละเอียดจะอัปเดตข้อมูลแคมเปญและ marker ไม่ใช่การตรวจพบเดิม
• เมื่อมี campaign.trait?.marker หรือฟิลด์แคมเปญที่ปรับละเอียดแล้ว ให้คงค่าไว้แม้ callback ถัดมาใน segment จะไม่มี marker หรือมีข้อมูลไม่ครบกว่า
• เมื่อตรวจพบ campaign.materialId อื่น ให้เพิ่มแถวปัจจุบันใหม่และปิด segment ก่อนหน้า โดยไม่ใช้การปรับละเอียดที่ล่าช้ากับแถวเก่านั้น

ตัวอย่างเช่น A(activity-1) -> A'(activity-1, marker) -> A(activity-1, marker miss) ยังคงเป็นหนึ่งแถว ส่วน A(activity-1) -> B(activity-2) -> delayed A'(activity-1) จะคง B เป็นรายการปัจจุบันและไม่เปลี่ยน A ในประวัติ

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

หากต้องการเริ่มการรู้จำเสียง ให้เรียก 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