หน้านี้ได้รับการแปลโดย Cloud Translation API

อ่าน SDK ของ Engage: คำแนะนำการผสานรวมทางเทคนิคของบุคคลที่สาม

กระตุ้นการมีส่วนร่วมในแอปด้วยการเข้าถึงผู้ใช้ในที่ที่ผู้ใช้อยู่ ผสานรวม Engage SDK เพื่อส่งคำแนะนำที่ปรับเปลี่ยนตามการใช้งานของผู้ใช้และเนื้อหาต่อเนื่องไปยัง ผู้ใช้โดยตรงในแพลตฟอร์มต่างๆ ในอุปกรณ์ เช่น คอลเล็กชัน, Entertainment Space และ Google Play Store การผสานรวมจะเพิ่มขนาด APK โดยเฉลี่ยไม่ถึง 50 KB (บีบอัด) และใช้เวลาของนักพัฒนาแอปประมาณ 1 สัปดาห์สำหรับแอปส่วนใหญ่ ดูข้อมูลเพิ่มเติมได้ที่เว็บไซต์ ธุรกิจ

คู่มือนี้มีวิธีการสำหรับพาร์ทเนอร์นักพัฒนาซอฟต์แวร์ในการส่งเนื้อหาการอ่าน (อีบุ๊ก หนังสือเสียง การ์ตูน/มังงะ) ไปยังแพลตฟอร์มเนื้อหา Engage

รายละเอียดการผสานรวม

คำศัพท์

การผสานรวมนี้มีคลัสเตอร์ 3 ประเภท ได้แก่ คำแนะนำ ดูต่อ และแนะนำ

คลัสเตอร์คำแนะนำจะแสดงคำแนะนำเนื้อหาที่ปรับเปลี่ยนในแบบของคุณให้อ่าน จากพาร์ทเนอร์นักพัฒนาแอปแต่ละราย

คำแนะนำจะมีโครงสร้างดังนี้
- คลัสเตอร์คำแนะนำ: มุมมอง UI ที่มีกลุ่มคำแนะนำจากพาร์ทเนอร์นักพัฒนาแอปรายเดียว
  
  รูปที่ 1 UI ของ Entertainment Space ที่แสดง กลุ่มคำแนะนำจากพาร์ทเนอร์รายเดียว
- เอนทิตี: ออบเจ็กต์ที่แสดงรายการเดียวในคลัสเตอร์ เอนทิตี อาจเป็น eBook, หนังสือเสียง, หนังสือชุด และอื่นๆ ดูรายการประเภทเอนทิตีที่รองรับได้ในส่วนระบุข้อมูลเอนทิตี
  
  รูปที่ 2 UI ของ Entertainment Space ที่แสดงเอนทิตีเดียวภายในคลัสเตอร์คำแนะนำของพาร์ทเนอร์รายเดียว
คลัสเตอร์ความต่อเนื่องจะแสดงหนังสือที่อ่านค้างไว้จากพาร์ทเนอร์นักพัฒนาแอปหลายราย ในการจัดกลุ่ม UI เดียว พาร์ทเนอร์นักพัฒนาแอปแต่ละรายจะได้รับอนุญาตให้ ออกอากาศเอนทิตีได้สูงสุด 10 รายการในคลัสเตอร์การติดตาม

รูปที่ 3 UI ของ Entertainment Space แสดง คลัสเตอร์ความต่อเนื่องที่มีคำแนะนำที่ดูค้างไว้จากพาร์ทเนอร์หลายราย (ปัจจุบันมองเห็นคำแนะนำเพียงรายการเดียว)
คลัสเตอร์แนะนำจะแสดงรายการที่เลือกจากพาร์ทเนอร์นักพัฒนาแอปหลายรายในการจัดกลุ่ม UI เดียว โดยจะมีคลัสเตอร์ "แนะนำ" เพียงคลัสเตอร์เดียว ซึ่งจะแสดงที่ด้านบนของ UI พร้อมการจัดวางที่มีลำดับความสำคัญสูงกว่าคลัสเตอร์คำแนะนำทั้งหมด พาร์ทเนอร์นักพัฒนาแอปแต่ละรายจะได้รับอนุญาตให้ ออกอากาศเอนทิตีได้สูงสุด 10 รายการในคลัสเตอร์แนะนำ

รูปที่ 4 UI ของ Entertainment Space ที่แสดงคลัสเตอร์แนะนำ พร้อมคำแนะนำจากพาร์ทเนอร์หลายราย (ปัจจุบันแสดงคำแนะนำเพียงรายการเดียว)

สิ่งที่ต้องเตรียมก่อนดำเนินการ

ระดับ API ขั้นต่ำ: 19

เพิ่มไลบรารี com.google.android.engage:engage-core ลงในแอป

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.5.2'
}

สรุป

การออกแบบนี้อิงตามการใช้งานบริการ ที่เชื่อมโยง

ข้อมูลที่ไคลเอ็นต์เผยแพร่ได้จะขึ้นอยู่กับขีดจำกัดต่อไปนี้สำหรับคลัสเตอร์ประเภทต่างๆ

ประเภทคลัสเตอร์	ขีดจำกัดของคลัสเตอร์	ขีดจำกัดสูงสุดของเอนทิตีในคลัสเตอร์
คลัสเตอร์คำแนะนำ	ไม่เกิน 7	สูงสุด 50 รายการ
คลัสเตอร์ความต่อเนื่อง	มากที่สุด 1	สูงสุด 20
คลัสเตอร์แนะนำ	มากที่สุด 1	สูงสุด 20

ขั้นตอนที่ 1: ระบุข้อมูลนิติบุคคล

SDK ได้กำหนดเอนทิตีต่างๆ เพื่อแสดงรายการแต่ละประเภท เรารองรับ เอนทิตีต่อไปนี้สำหรับหมวดหมู่ "อ่าน"

EbookEntity
AudiobookEntity
BookSeriesEntity

แผนภูมิด้านล่างแสดงแอตทริบิวต์ที่มีและข้อกำหนดสำหรับแต่ละประเภท

`EbookEntity`

ออบเจ็กต์ EbookEntity แสดงถึง eBook (เช่น eBook ของ Becoming โดย Michelle Obama)

แอตทริบิวต์	ข้อกำหนด	หมายเหตุ
ชื่อ	ต้องระบุ
ภาพโปสเตอร์	ต้องระบุ	ต้องระบุรูปภาพอย่างน้อย 1 ภาพ ดูคำแนะนำได้ที่ข้อกำหนด ของรูปภาพ
ผู้เขียน	ต้องระบุ	ต้องระบุชื่อผู้เขียนอย่างน้อย 1 ชื่อ
URI ของลิงก์การดำเนินการ	ต้องระบุ	Deep Link ไปยังแอปของผู้ให้บริการสำหรับอีบุ๊ก หมายเหตุ: คุณใช้ Deep Link สำหรับการระบุแหล่งที่มาได้ โปรดดูคำถามที่พบบ่อยนี้
วันที่เผยแพร่	ไม่บังคับ	ในรูปแบบมิลลิวินาทีของ Epoch หากมี
คำอธิบาย	ไม่บังคับ	ต้องมีความยาวไม่เกิน 200 อักขระหากระบุ
ราคา	ไม่บังคับ	ข้อความอิสระ
จำนวนหน้า	ไม่บังคับ	ต้องเป็นจำนวนเต็มบวกหากระบุ
ประเภท	ไม่บังคับ	รายการประเภทที่เชื่อมโยงกับหนังสือ
ชื่อหนังสือชุด	ไม่บังคับ	ชื่อชุดหนังสือที่อีบุ๊กเป็นส่วนหนึ่ง (เช่น Harry Potter)
ดัชนีหน่วยของซีรีส์	ไม่บังคับ	ดัชนีของ eBook ในชุด โดย 1 คือ eBook เล่มแรกในชุด เช่น หากแฮร์รี่ พอตเตอร์กับนักโทษแห่ง อัซคาบันเป็นหนังสือเล่มที่ 3 ในชุด คุณควรตั้งค่านี้เป็น 3
ประเภทหนังสือต่อเนื่อง	ไม่บังคับ	TYPE_CONTINUE - อ่านหนังสือที่อ่านค้างไว้ต่อ TYPE_NEXT - อ่านต่อในเล่มใหม่ของชุดหนังสือ TYPE_NEW - เพิ่งเปิดตัว
เวลาในการมีส่วนร่วมครั้งล่าสุด	ต้องมีแบบมีเงื่อนไข	ต้องระบุเมื่อรายการอยู่ในคลัสเตอร์ความต่อเนื่อง อีบุ๊กที่เพิ่งซื้อใหม่จะแสดงในกลุ่ม "อ่านต่อ" ได้ ในหน่วยมิลลิวินาทีของ Epoch
เปอร์เซ็นต์ความคืบหน้า	ต้องมีแบบมีเงื่อนไข	ต้องระบุเมื่อรายการอยู่ในคลัสเตอร์ความต่อเนื่อง ค่าต้องมากกว่า 0 และน้อยกว่า 100
DisplayTimeWindow - กำหนดกรอบเวลาสำหรับเนื้อหา ที่จะแสดงในแพลตฟอร์ม
การประทับเวลาเริ่มต้น	ไม่บังคับ	การประทับเวลา Epoch หลังจากที่ควรแสดงเนื้อหาบน แพลตฟอร์ม หากไม่ได้ตั้งค่าไว้ เนื้อหาจะมีสิทธิ์แสดงในแพลตฟอร์ม ในหน่วยมิลลิวินาทีของ Epoch
การประทับเวลาสิ้นสุด	ไม่บังคับ	การประทับเวลา Epoch หลังจากที่ระบบจะไม่แสดงเนื้อหาบนแพลตฟอร์มอีกต่อไป หากไม่ได้ตั้งค่าไว้ เนื้อหาจะมีสิทธิ์แสดงในแพลตฟอร์ม ในหน่วยมิลลิวินาทีของ Epoch

`AudiobookEntity`

ออบเจ็กต์ AudiobookEntity แสดงถึงหนังสือเสียง (เช่น หนังสือเสียงของ Becoming โดย Michelle Obama)

แอตทริบิวต์	ข้อกำหนด	หมายเหตุ
ชื่อ	ต้องระบุ
ภาพโปสเตอร์	ต้องระบุ	ต้องระบุรูปภาพอย่างน้อย 1 ภาพ ดูคำแนะนำได้ที่ข้อกำหนด ของรูปภาพ
ผู้เขียน	ต้องระบุ	ต้องระบุชื่อผู้เขียนอย่างน้อย 1 ชื่อ
URI ของลิงก์การดำเนินการ	ต้องระบุ	Deep Link ไปยังแอปของผู้ให้บริการสำหรับหนังสือเสียง หมายเหตุ: คุณใช้ Deep Link สำหรับการระบุแหล่งที่มาได้ โปรดดูคำถามที่พบบ่อยนี้
ผู้บรรยาย	ไม่บังคับ	ต้องระบุชื่อผู้บรรยายอย่างน้อย 1 คน
วันที่เผยแพร่	ไม่บังคับ	ในรูปแบบมิลลิวินาทีของ Epoch หากมี
คำอธิบาย	ไม่บังคับ	ต้องมีความยาวไม่เกิน 200 อักขระหากระบุ
ราคา	ไม่บังคับ	ข้อความอิสระ
ระยะเวลา	ไม่บังคับ	ต้องเป็นค่าบวกหากระบุ
ประเภท	ไม่บังคับ	รายการประเภทที่เชื่อมโยงกับหนังสือ
ชื่อหนังสือชุด	ไม่บังคับ	ชื่อชุดหนังสือที่หนังสือเสียงเป็นของชุดนั้น (เช่น Harry Potter)
ดัชนีหน่วยของซีรีส์	ไม่บังคับ	ดัชนีของหนังสือเสียงในชุด โดย 1 คือหนังสือเสียงเล่มแรก ในชุด เช่น หากแฮร์รี่ พอตเตอร์กับนักโทษแห่ง อัซคาบันเป็นหนังสือเล่มที่ 3 ในชุด คุณควรตั้งค่านี้เป็น 3
ประเภทหนังสือต่อเนื่อง	ไม่บังคับ	TYPE_CONTINUE - อ่านหนังสือที่อ่านค้างไว้ต่อ TYPE_NEXT - อ่านต่อในเล่มใหม่ของชุดหนังสือ TYPE_NEW - เพิ่งเปิดตัว
เวลาในการมีส่วนร่วมครั้งล่าสุด	ต้องมีแบบมีเงื่อนไข	ต้องระบุเมื่อรายการอยู่ในคลัสเตอร์ความต่อเนื่อง ในหน่วยมิลลิวินาทีของ Epoch
เปอร์เซ็นต์ความคืบหน้า	ต้องมีแบบมีเงื่อนไข	ต้องระบุเมื่อรายการอยู่ในคลัสเตอร์ความต่อเนื่อง หนังสือเสียงที่เพิ่งซื้อใหม่จะอยู่ในกลุ่มอ่านต่อ ได้ ค่าต้องมากกว่า 0 และน้อยกว่า 100
DisplayTimeWindow - กำหนดกรอบเวลาสำหรับเนื้อหา ที่จะแสดงในแพลตฟอร์ม
การประทับเวลาเริ่มต้น	ไม่บังคับ	การประทับเวลา Epoch หลังจากที่ควรแสดงเนื้อหาบน แพลตฟอร์ม หากไม่ได้ตั้งค่าไว้ เนื้อหาจะมีสิทธิ์แสดงในแพลตฟอร์ม ในหน่วยมิลลิวินาทีของ Epoch
การประทับเวลาสิ้นสุด	ไม่บังคับ	การประทับเวลา Epoch หลังจากที่ระบบจะไม่แสดงเนื้อหาบนแพลตฟอร์มอีกต่อไป หากไม่ได้ตั้งค่าไว้ เนื้อหาจะมีสิทธิ์แสดงในแพลตฟอร์ม ในหน่วยมิลลิวินาทีของ Epoch

`BookSeriesEntity`

ออบเจ็กต์ BookSeriesEntity แสดงถึงชุดหนังสือ (เช่น ชุดหนังสือแฮร์รี่ พอตเตอร์ ซึ่งมีหนังสือ 7 เล่ม)

แอตทริบิวต์	ข้อกำหนด	หมายเหตุ
ชื่อ	ต้องระบุ
ภาพโปสเตอร์	ต้องระบุ	ต้องระบุรูปภาพอย่างน้อย 1 ภาพ ดูคำแนะนำได้ที่ข้อกำหนด ของรูปภาพ
ผู้เขียน	ต้องระบุ	ต้องระบุชื่อผู้แต่งอย่างน้อย 1 ชื่อ
URI ของลิงก์การดำเนินการ	ต้องระบุ	Deep Link ไปยังแอปของผู้ให้บริการสำหรับหนังสือเสียงหรือ eBook หมายเหตุ: คุณใช้ Deep Link สำหรับการระบุแหล่งที่มาได้ โปรดดูคำถามที่พบบ่อยนี้
จำนวนหนังสือ	ต้องระบุ	จำนวนหนังสือในชุด
คำอธิบาย	ไม่บังคับ	ต้องมีความยาวไม่เกิน 200 อักขระหากระบุ
ประเภท	ไม่บังคับ	รายการประเภทที่เชื่อมโยงกับหนังสือ
ประเภทหนังสือต่อเนื่อง	ไม่บังคับ	TYPE_CONTINUE - อ่านหนังสือที่อ่านค้างไว้ต่อ TYPE_NEXT - อ่านต่อในเล่มใหม่ของชุดหนังสือ TYPE_NEW - เพิ่งเปิดตัว
เวลาในการมีส่วนร่วมครั้งล่าสุด	ต้องมีแบบมีเงื่อนไข	ต้องระบุเมื่อรายการอยู่ในคลัสเตอร์ความต่อเนื่อง ในหน่วยมิลลิวินาทีของ Epoch
เปอร์เซ็นต์ความคืบหน้า	ต้องมีแบบมีเงื่อนไข	ต้องระบุเมื่อรายการอยู่ในคลัสเตอร์ความต่อเนื่อง ชุดหนังสือที่เพิ่งซื้อใหม่จะแสดงในคลัสเตอร์ "อ่านต่อ" ได้ ค่าต้องมากกว่า 0 และน้อยกว่า 100
DisplayTimeWindow - กำหนดกรอบเวลาสำหรับเนื้อหา ที่จะแสดงในแพลตฟอร์ม
การประทับเวลาเริ่มต้น	ไม่บังคับ	การประทับเวลา Epoch หลังจากที่ควรแสดงเนื้อหาบน แพลตฟอร์ม หากไม่ได้ตั้งค่าไว้ เนื้อหาจะมีสิทธิ์แสดงในแพลตฟอร์ม ในหน่วยมิลลิวินาทีของ Epoch
การประทับเวลาสิ้นสุด	ไม่บังคับ	การประทับเวลา Epoch หลังจากที่ระบบจะไม่แสดงเนื้อหาบนแพลตฟอร์มอีกต่อไป หากไม่ได้ตั้งค่าไว้ เนื้อหาจะมีสิทธิ์แสดงในแพลตฟอร์ม ในหน่วยมิลลิวินาทีของ Epoch

ข้อกำหนดเกี่ยวกับรูปภาพ

ข้อกำหนดที่จำเป็นสำหรับชิ้นงานรูปภาพแสดงอยู่ด้านล่าง

สัดส่วนภาพ	ข้อกำหนด	พิกเซลขั้นต่ำ	พิกเซลที่แนะนํา
สี่เหลี่ยมจัตุรัส (1x1)	ต้องระบุ	300x300	1200x1200
แนวนอน (1.91x1)	ไม่บังคับ	600x314	1200x628
แนวตั้ง (4x5)	ไม่บังคับ	480x600	960x1200

รูปแบบไฟล์

PNG, JPG, GIF แบบภาพนิ่ง, WebP

ขนาดไฟล์สูงสุด

5120 KB

คำแนะนำเพิ่มเติม

พื้นที่ปลอดภัยของรูปภาพ: ใส่เนื้อหาที่สําคัญไว้ตรงกลาง 80% ของ รูปภาพ

ตัวอย่าง

AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(
                      new Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .build();

ขั้นตอนที่ 2: ระบุข้อมูลคลัสเตอร์

ขอแนะนำให้เรียกใช้งานการเผยแพร่เนื้อหาในเบื้องหลัง (เช่น ใช้ WorkManager) และกำหนดเวลาเป็นประจำหรือตามเหตุการณ์ (เช่น ทุกครั้งที่ ผู้ใช้เปิดแอปหรือเมื่อผู้ใช้เพิ่งเพิ่มสินค้าลงในรถเข็น)

AppEngagePublishClient มีหน้าที่เผยแพร่คลัสเตอร์ API ต่อไปนี้พร้อมใช้งานในไคลเอ็นต์

isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishContinuationCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteContinuationCluster
deleteUserManagementCluster
deleteClusters

`isServiceAvailable`

API นี้ใช้เพื่อตรวจสอบว่าบริการพร้อมใช้งานสำหรับการผสานรวมหรือไม่ และ สามารถแสดงเนื้อหาในอุปกรณ์ได้หรือไม่

Kotlin

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content
          // publish calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

หมายเหตุ: เราขอแนะนำอย่างยิ่งให้เรียกใช้ชื่องานเป็นระยะๆ เพื่อตรวจสอบว่าบริการพร้อมใช้งานในภายหลังหรือไม่ ความพร้อมให้บริการอาจเปลี่ยนแปลงเมื่อมีการอัปเกรดเวอร์ชัน Android, อัปเกรดแอป, ติดตั้ง และถอนการติดตั้ง การตรวจสอบงานเป็นระยะๆ ในช่วงเวลาหนึ่งๆ จะช่วยให้เผยแพร่ข้อมูลได้เมื่อบริการพร้อมใช้งาน

`publishRecommendationClusters`

API นี้ใช้เพื่อเผยแพร่รายการออบเจ็กต์ RecommendationCluster

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .build())
                .build());

เมื่อบริการได้รับคำขอ ระบบจะดำเนินการต่อไปนี้ภายในธุรกรรมเดียว

ระบบจะนำข้อมูล RecommendationCluster ที่มีอยู่จากพาร์ทเนอร์นักพัฒนาออก
ระบบจะแยกวิเคราะห์และจัดเก็บข้อมูลจากคำขอในคลัสเตอร์คำแนะนำที่อัปเดต

ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธคำขอทั้งหมดและคงสถานะเดิมไว้

`publishFeaturedCluster`

API นี้ใช้เพื่อเผยแพร่รายการออบเจ็กต์ FeaturedCluster

Kotlin

client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        ...
                        .build())
                .build());

เมื่อบริการได้รับคำขอ ระบบจะดำเนินการต่อไปนี้ภายในธุรกรรมเดียว

ระบบจะนำข้อมูล FeaturedCluster ที่มีอยู่จากพาร์ทเนอร์นักพัฒนาออก
ระบบจะแยกวิเคราะห์และจัดเก็บข้อมูลจากคำขอในคลัสเตอร์แนะนำที่อัปเดต

ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธคำขอทั้งหมดและคงสถานะเดิมไว้

`publishContinuationCluster`

ใช้ API นี้เพื่อเผยแพร่ออบเจ็กต์ ContinuationCluster

Kotlin

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

Java

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

เมื่อบริการได้รับคำขอ ระบบจะดำเนินการต่อไปนี้ภายในธุรกรรมเดียว

ระบบจะนำข้อมูล ContinuationCluster ที่มีอยู่จากพาร์ทเนอร์นักพัฒนาออก
ระบบจะแยกวิเคราะห์และจัดเก็บข้อมูลจากคำขอใน Continuation Cluster ที่อัปเดต

ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธคำขอทั้งหมดและคงสถานะเดิมไว้

`publishUserAccountManagementRequest`

API นี้ใช้เพื่อเผยแพร่การ์ดลงชื่อเข้าใช้ การดำเนินการลงชื่อเข้าใช้นำผู้ใช้ไปยังหน้าลงชื่อเข้าใช้ของแอปเพื่อให้แอปเผยแพร่เนื้อหา (หรือแสดงเนื้อหาที่ปรับเปลี่ยนในแบบของคุณมากขึ้น) ได้

ข้อมูลเมตาต่อไปนี้เป็นส่วนหนึ่งของการ์ดลงชื่อเข้าใช้

แอตทริบิวต์	ข้อกำหนด	คำอธิบาย
URI ของการดำเนินการ	ต้องระบุ	Deep Link ไปยังการดำเนินการ (เช่น ไปยังหน้าลงชื่อเข้าใช้แอป)
รูปภาพ	ไม่บังคับ - หากไม่ได้ระบุ ต้องระบุชื่อ	รูปภาพที่แสดงในการ์ด รูปภาพที่มีสัดส่วนภาพ 16x9 และความละเอียด 1264x712
ชื่อ	ไม่บังคับ - หากไม่ได้ระบุไว้ จะต้องระบุรูปภาพ	ชื่อบนบัตร
ข้อความการดำเนินการ	ไม่บังคับ	ข้อความที่แสดงใน CTA (เช่น ลงชื่อเข้าใช้)
ชื่อรอง	ไม่บังคับ	คำบรรยายแทนเสียงที่ไม่บังคับในการ์ด

Kotlin

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

เมื่อบริการได้รับคำขอ ระบบจะดำเนินการต่อไปนี้ภายในธุรกรรมเดียว

ระบบจะนำข้อมูล UserAccountManagementCluster ที่มีอยู่จากพาร์ทเนอร์นักพัฒนาออก
ระบบจะแยกวิเคราะห์และจัดเก็บข้อมูลจากคำขอในคลัสเตอร์ UserAccountManagementCluster ที่อัปเดต

ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธคำขอทั้งหมดและคงสถานะเดิมไว้

`updatePublishStatus`

หากไม่มีการเผยแพร่คลัสเตอร์ใดเลยเนื่องด้วยเหตุผลทางธุรกิจภายใน เราขอแนะนำให้อัปเดตสถานะการเผยแพร่โดยใช้ API updatePublishStatus ซึ่งเป็นสิ่งสำคัญเนื่องจากเหตุผลต่อไปนี้

การระบุสถานะในทุกสถานการณ์ แม้ว่าเนื้อหาจะเผยแพร่แล้ว (STATUS == PUBLISHED) ก็มีความสำคัญอย่างยิ่งต่อการสร้างแดชบอร์ดที่ใช้สถานะที่ชัดเจนนี้ เพื่อสื่อถึงสถานภาพและเมตริกอื่นๆ ของการผสานรวม
หากไม่มีการเผยแพร่เนื้อหา แต่สถานะการผสานรวมไม่ขาดตอน (STATUS == NOT_PUBLISHED) Google จะหลีกเลี่ยงการทริกเกอร์การแจ้งเตือนในแดชบอร์ด สุขภาพของแอปได้ โดยจะยืนยันว่าเนื้อหาไม่ได้เผยแพร่เนื่องจากสถานการณ์ที่คาดการณ์ไว้จากมุมมองของผู้ให้บริการ
ซึ่งจะช่วยให้นักพัฒนาแอปได้รับข้อมูลเชิงลึกเกี่ยวกับเวลาที่เผยแพร่ข้อมูลเทียบกับเวลาที่ไม่ได้เผยแพร่
Google อาจใช้รหัสสถานะเพื่อกระตุ้นให้ผู้ใช้ดำเนินการบางอย่างในแอป เพื่อให้ผู้ใช้เห็นเนื้อหาของแอปหรือแก้ไขปัญหา

รหัสสถานะการเผยแพร่ที่มีสิทธิ์มีดังนี้

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

หากเนื้อหาไม่ได้เผยแพร่เนื่องจากผู้ใช้ไม่ได้เข้าสู่ระบบ Google ขอแนะนำให้เผยแพร่การ์ดลงชื่อเข้าใช้ หากผู้ให้บริการไม่สามารถเผยแพร่การ์ดลงชื่อเข้าใช้ได้ไม่ว่าด้วยเหตุผลใดก็ตาม เราขอแนะนำให้เรียกใช้ API updatePublishStatus ด้วยรหัสสถานะ NOT_PUBLISHED_REQUIRES_SIGN_IN

Kotlin

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

`deleteRecommendationClusters`

API นี้ใช้เพื่อลบเนื้อหาของคลัสเตอร์คำแนะนำ

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

เมื่อได้รับคำขอ บริการจะนำข้อมูลที่มีอยู่ออกจากคลัสเตอร์คำแนะนำ ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธคำขอทั้งหมด และคงสถานะเดิมไว้

`deleteFeaturedCluster`

API นี้ใช้เพื่อลบเนื้อหาของคลัสเตอร์แนะนำ

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

เมื่อได้รับคำขอ บริการจะนำข้อมูลที่มีอยู่ออกจาก คลัสเตอร์แนะนำ ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธคำขอทั้งหมด และคงสถานะเดิมไว้

`deleteContinuationCluster`

API นี้ใช้เพื่อลบเนื้อหาของคลัสเตอร์การต่อเนื่อง

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

เมื่อได้รับคำขอ บริการจะนำข้อมูลที่มีอยู่ออกจาก คลัสเตอร์การต่อเนื่อง ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธคำขอทั้งหมด และคงสถานะเดิมไว้

`deleteUserManagementCluster`

API นี้ใช้เพื่อลบเนื้อหาของคลัสเตอร์ UserAccountManagement

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

เมื่อบริการได้รับคำขอแล้ว ระบบจะนำข้อมูลที่มีอยู่ออกจากคลัสเตอร์ UserAccountManagement ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธคำขอทั้งหมดและคงสถานะเดิมไว้

`deleteClusters`

API นี้ใช้เพื่อลบเนื้อหาของคลัสเตอร์ประเภทหนึ่งๆ

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      ...
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                ...
                .build());

เมื่อได้รับคำขอ บริการจะนำข้อมูลที่มีอยู่ออกจากคลัสเตอร์ทั้งหมดที่ตรงกับประเภทคลัสเตอร์ที่ระบุ ไคลเอ็นต์เลือกส่งคลัสเตอร์ประเภทเดียวหรือหลายประเภทได้ ในกรณีที่เกิดข้อผิดพลาด ระบบจะปฏิเสธคำขอทั้งหมดและคงสถานะเดิมไว้

การจัดการข้อผิดพลาด

เราขอแนะนำอย่างยิ่งให้รับฟังผลลัพธ์ของงานจาก API การเผยแพร่ เช่น เพื่อให้ดำเนินการติดตามผลเพื่อกู้คืนและส่งงานที่สำเร็จอีกครั้งได้

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

ข้อผิดพลาดจะแสดงเป็น AppEngageException พร้อมสาเหตุที่รวมเป็นรหัสข้อผิดพลาด

รหัสข้อผิดพลาด	ชื่อข้อผิดพลาด	หมายเหตุ
`1`	`SERVICE_NOT_FOUND`	บริการไม่พร้อมใช้งานในอุปกรณ์ที่ระบุ
`2`	`SERVICE_NOT_AVAILABLE`	บริการพร้อมใช้งานในอุปกรณ์ที่ระบุ แต่ไม่พร้อมใช้งาน ในเวลาที่โทร (เช่น ปิดใช้บริการอย่างชัดเจน)
`3`	`SERVICE_CALL_EXECUTION_FAILURE`	การดำเนินการงานล้มเหลวเนื่องจากปัญหาการแยกเธรด ในกรณีนี้ คุณสามารถ ลองอีกครั้งได้
`4`	`SERVICE_CALL_PERMISSION_DENIED`	ผู้โทรไม่ได้รับอนุญาตให้โทรหาบริการ
`5`	`SERVICE_CALL_INVALID_ARGUMENT`	คำขอมีข้อมูลที่ไม่ถูกต้อง (เช่น มีคลัสเตอร์มากกว่าจำนวนที่อนุญาต)
`6`	`SERVICE_CALL_INTERNAL`	เกิดข้อผิดพลาดที่ฝั่งบริการ
`7`	`SERVICE_CALL_RESOURCE_EXHAUSTED`	มีการเรียกใช้บริการบ่อยเกินไป

ขั้นตอนที่ 3: จัดการ Intent การออกอากาศ

นอกเหนือจากการเรียกใช้ API การเผยแพร่เนื้อหาผ่านงานแล้ว คุณยังต้องตั้งค่า BroadcastReceiver เพื่อรับ คำขอเผยแพร่เนื้อหาด้วย

เป้าหมายของความตั้งใจในการออกอากาศคือการเปิดใช้งานแอปอีกครั้งและการบังคับซิงค์ข้อมูลเป็นหลัก Broadcast Intents ไม่ได้ออกแบบมาให้ส่งบ่อยมาก ระบบจะทริกเกอร์การอัปเดตก็ต่อเมื่อบริการ Engage ระบุว่าเนื้อหาอาจล้าสมัย (เช่น มีอายุ 1 สัปดาห์) ด้วยวิธีนี้ ผู้ใช้จึงมั่นใจได้มากขึ้นว่าจะได้รับประสบการณ์การใช้งานเนื้อหาใหม่ๆ แม้ว่าจะไม่ได้เรียกใช้แอปพลิเคชันเป็นเวลานานก็ตาม

ต้องตั้งค่า BroadcastReceiver ด้วย 2 วิธีต่อไปนี้

ลงทะเบียนอินสแตนซ์ของคลาส BroadcastReceiver แบบไดนามิกโดยใช้ Context.registerReceiver() ซึ่งจะช่วยให้แอปพลิเคชันที่ยังคงทำงานอยู่ในหน่วยความจำสื่อสารได้

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
  // is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
  // Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
  // received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

Java

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

}

ประกาศการติดตั้งใช้งานแบบคงที่ด้วยแท็ก <receiver> ในไฟล์ AndroidManifest.xml ซึ่งจะช่วยให้แอปพลิเคชันรับ Broadcast Intent ได้เมื่อไม่ได้ทำงานอยู่ และยังช่วยให้แอปพลิเคชันเผยแพร่ เนื้อหาได้ด้วย

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

บริการจะส่ง Intent ต่อไปนี้

com.google.android.engage.action.PUBLISH_RECOMMENDATION เราขอแนะนำให้เริ่มการโทร publishRecommendationClusters เมื่อ ได้รับความตั้งใจนี้
com.google.android.engage.action.PUBLISH_FEATURED ขอแนะนำให้เริ่มpublishFeaturedClusterเมื่อได้รับ เจตนานี้
com.google.android.engage.action.PUBLISH_CONTINUATIONIt is recommended to start apublishContinuationCluster` เมื่อได้รับ Intent นี้

เวิร์กโฟลว์การผสานรวม

ดูคำแนะนำแบบทีละขั้นตอนเกี่ยวกับการยืนยันการผสานรวมหลังจากเสร็จสมบูรณ์ได้ที่ เวิร์กโฟลว์การผสานรวมนักพัฒนาแอป Engage

คำถามที่พบบ่อย

ดูคำถามที่พบบ่อยได้ที่คำถามที่พบบ่อยเกี่ยวกับ Engage SDK

รายชื่อติดต่อ

โปรดติดต่อ engage-developers@google.com หากมีคำถามในระหว่าง กระบวนการผสานรวม ทีมของเราจะตอบกลับโดยเร็วที่สุด

ขั้นตอนถัดไป

หลังจากผสานรวมเสร็จสมบูรณ์แล้ว ขั้นตอนถัดไปมีดังนี้

ส่งอีเมลไปที่ engage-developers@google.com และแนบ APK ที่ผสานรวมแล้วซึ่งพร้อมให้ Google ทดสอบ
Google จะดำเนินการยืนยันและตรวจสอบภายในเพื่อให้มั่นใจว่าการผสานรวมทำงานได้ตามที่คาดไว้ หากจำเป็นต้องเปลี่ยนแปลง Google จะติดต่อคุณ พร้อมรายละเอียดที่จำเป็น
เมื่อการทดสอบเสร็จสมบูรณ์และไม่จำเป็นต้องทำการเปลี่ยนแปลงใดๆ Google จะติดต่อคุณเพื่อ แจ้งให้ทราบว่าคุณเริ่มเผยแพร่ APK ที่อัปเดตและผสานรวมไปยัง Play Store ได้แล้ว
หลังจาก Google ยืนยันว่า APK ที่อัปเดตแล้วได้รับการเผยแพร่ใน Play Store แล้ว ระบบจะเผยแพร่คลัสเตอร์แนะนำ แนะนำ และเล่นต่อ และผู้ใช้จะมองเห็นคลัสเตอร์ดังกล่าว