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

จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

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

เอกสารนี้มีวิธีการสำหรับพาร์ทเนอร์นักพัฒนาแอปในการผสานรวมเนื้อหาโซเชียลโดยใช้ Engage SDK เพื่อแสดงข้อมูลในแพลตฟอร์มใหม่นี้

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

ส่วนต่อไปนี้จะแสดงรายละเอียดการผสานรวม

คำศัพท์

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

คําแนะนําของคุณควรมีโครงสร้างดังต่อไปนี้

คลัสเตอร์คําแนะนํา: มุมมอง UI ที่มีกลุ่มคําแนะนําจากพาร์ทเนอร์นักพัฒนาแอปรายเดียวกัน

คลัสเตอร์คําแนะนําแต่ละรายการประกอบด้วยเอนทิตีประเภทใดประเภทหนึ่งต่อไปนี้

• PortraitMediaEntity
• SocialPostEntity

PortraitMediaEntity ต้องมีรูปภาพแนวตั้ง 1 รูปสำหรับโพสต์ ข้อมูลเมตาที่เกี่ยวข้องกับโปรไฟล์และการโต้ตอบเป็นข้อมูลที่ไม่บังคับ

• โพสต์

  • รูปภาพในโหมดแนวตั้งและการประทับเวลา หรือ
  • รูปภาพในโหมดแนวตั้ง + เนื้อหาข้อความและการประทับเวลา

• โปรไฟล์

  • รูปโปรไฟล์ ชื่อหรือแฮนเดิล รูปภาพเพิ่มเติม

• การโต้ตอบ

  • นับและติดป้ายกำกับเท่านั้น หรือ
  • จํานวนและความชัดเจน (ไอคอน)

SocialPostEntity มีข้อมูลเมตาที่เกี่ยวข้องกับโปรไฟล์ โพสต์ และการโต้ตอบ

• โปรไฟล์

  • รูปโปรไฟล์ ชื่อหรือแฮนเดิล ข้อความเพิ่มเติม รูปภาพเพิ่มเติม

• โพสต์

  • ข้อความและการประทับเวลา หรือ
  • ริชมีเดีย (รูปภาพหรือ URL แบบริชมีเดีย) และการประทับเวลา หรือ
  • ข้อความและริชมีเดีย (รูปภาพหรือ URL แบบริชมีเดีย) และการประทับเวลา หรือ
  • ตัวอย่างวิดีโอ (ภาพปกและระยะเวลา) และการประทับเวลา

• การโต้ตอบ

  • นับและติดป้ายกํากับเท่านั้น หรือ
  • จํานวนและความชัดเจน (ไอคอน)

งานก่อนเริ่มเวิร์กช็อป

ระดับ 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'
}

สรุป

การออกแบบนี้อิงตามการใช้งาน bound service

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

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

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

1. PortraitMediaEntity
2. SocialPostEntity

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

PortraitMediaEntity

SocialPostEntity

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

รูปภาพต้องโฮสต์ใน CDN สาธารณะเพื่อให้ Google เข้าถึงได้

รูปแบบไฟล์

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

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

5120 KB

คําแนะนําเพิ่มเติม

• พื้นที่ปลอดภัยของรูปภาพ: ใส่เนื้อหาสำคัญไว้ตรงกลาง ซึ่งก็คือ 80% ของรูปภาพนั้น
• ใช้พื้นหลังโปร่งใสเพื่อให้รูปภาพแสดงได้อย่างถูกต้องในการตั้งค่าธีมมืดและธีมสว่าง

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

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

AppEngageSocialClient มีหน้าที่รับผิดชอบในการเผยแพร่คลัสเตอร์โซเชียล

API ต่อไปนี้ใช้เพื่อเผยแพร่คลัสเตอร์ในไคลเอ็นต์

• isServiceAvailable
• publishRecommendationClusters
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

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

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

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

publishRecommendationClusters

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

ออบเจ็กต์ RecommendationCluster อาจมีแอตทริบิวต์ต่อไปนี้

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build())

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Latest from your friends")
                        .build())
                .build());

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

• ระบบจะนำข้อมูลคลัสเตอร์คําแนะนําที่มีอยู่ทั้งหมดออก
• ระบบจะแยกวิเคราะห์และจัดเก็บข้อมูลจากคําขอไว้ในคลัสเตอร์คําแนะนําใหม่

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

publishUserAccountManagementRequest

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

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

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

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

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

• การให้สถานะในทุกสถานการณ์ แม้ว่าเนื้อหาจะเผยแพร่แล้ว (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 จะแนะนำให้เผยแพร่การ์ดลงชื่อเข้าใช้ หากผู้ให้บริการไม่สามารถเผยแพร่การ์ดลงชื่อเข้าใช้ไม่ว่าด้วยเหตุผลใดก็ตาม เราขอแนะนำให้เรียกใช้ updatePublishStatus API ด้วยรหัสสถานะ NOT_PUBLISHED_REQUIRES_SIGN_IN

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

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

deleteRecommendationClusters

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

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

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

deleteUserManagementCluster

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

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

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

deleteClusters

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

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

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .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 โดยระบุสาเหตุเป็นรหัสข้อผิดพลาด

ขั้นตอนที่ 3: จัดการ Intent ของข้อความประกาศ

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

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

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

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

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION 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));

}

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

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

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

• com.google.android.engage.action.PUBLISH_RECOMMENDATION เราขอแนะนำให้เริ่มการเรียก publishRecommendationClusters เมื่อได้รับ Intent นี้

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

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

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

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

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

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

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

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

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