מעורבות SDK ברשתות חברתיות: הוראות לשילוב טכני של צד שלישי

כדי להגביר את ההתעניינות באפליקציה, כדאי להגיע למשתמשים במקומות שבהם הם נמצאים. אפשר לשלב את Engage SDK כדי להציג המלצות מותאמות אישית ותוכן להמשך ישירות למשתמשים בכמה פלטפורמות במכשיר, כמו אוספים, חבילת הבידור וחנות Play. השילוב מוסיף פחות מ-50KB (דחוסים) ל-APK הממוצע, ולוקח למפתחים בערך שבוע להטמיע אותו ברוב האפליקציות. מידע נוסף זמין באתר העסקי שלנו.

המדריך הזה כולל הוראות לשותפי פיתוח בנושא העברת תוכן של רשתות חברתיות לפלטפורמות התוכן של Engage.

תמיכה בקטגוריות ופלטפורמות

הזכאות לפלטפורמות של Engage SDK מבוססת על קטגוריית התוכן של האפליקציה. בטבלה הבאה מפורטות הדרישות שצריך לעמוד בהן כדי להציג מוצרים בפלטפורמות ספציפיות:

android skills add engage-sdk-integration

פרטי השילוב

בקטע הבא מפורטים פרטי השילוב.

הסברים על המונחים

אשכולות של המלצות מציגים הצעות בהתאמה אישית משותף פיתוח ספציפי.

ההמלצות מוצגות במבנה הבא:

אשכול המלצות: תצוגה בממשק המשתמש שמכילה קבוצת המלצות מאותו שותף פיתוח.

כל קבוצת המלצות מורכבת מאחד משני סוגי הישויות הבאים :

• PortraitMediaEntity
• SocialPostEntity

השדה PortraitMediaEntity חייב להכיל תמונה אחת לאורך בשביל הפוסט. המטא-נתונים שקשורים לפרופיל ולאינטראקציה הם אופציונליים.

• פוסט

  • תמונה במצב לאורך וחותמת זמן, או
  • תמונה במצב לאורך + תוכן טקסט וחותמת זמן

• פרופיל

  • דמות, שם או כינוי, תמונה נוספת

• אינטראקציות

  • ספירה ותיוג בלבד, או
  • מספר ורכיב חזותי (סמל)

הישות 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.6.0'
}

סיכום

העיצוב מבוסס על הטמעה של שרת מאגד (bound service).

הנתונים שלקוח יכול לפרסם כפופים למגבלות הבאות, בהתאם לסוגי האשכולות השונים:

שלב 1: מסירת נתוני הישות

ב-SDK מוגדרות ישויות שונות שמייצגות כל סוג פריט. ה-SDK תומך בישויות הבאות בקטגוריה "רשתות חברתיות":

1. PortraitMediaEntity
2. SocialPostEntity

בטבלאות הבאות מפורטים המאפיינים הזמינים והדרישות לכל סוג.

PortraitMediaEntity

SocialPostEntity

מפרט לתמונות

התמונות צריכות להתארח ברשתות CDN ציבוריות כדי ש-Google תוכל לגשת אליהן.

פורמט קובץ

‫PNG, ‏ JPG, ‏ GIF סטטי, WebP

גודל קובץ מקסימלי

5,120KB

המלצות נוספות

• האזור הבטוח בתמונה: צריך למקם את התוכן החשוב במרכז התמונה, והוא צריך להשתרע על פני 80% מהשטח שלה.
• כדאי להשתמש ברקע שקוף כדי שהתמונה תוצג כמו שצריך בהגדרות של עיצוב כהה ובהיר.

שלב 2: ציון נתונים של אוסף ההמשכים

מומלץ להפעיל את משימת פרסום התוכן ברקע (לדוגמה, באמצעות WorkManager) ולתזמן אותה באופן קבוע או על בסיס אירוע (לדוגמה, בכל פעם שהמשתמש פותח את האפליקציה או כשהמשתמש מתחיל לעקוב אחרי חשבון חדש).

‫AppEngageSocialClient אחראי לפרסום של אוספים חברתיים.

אלה ממשקי ה-API לפרסום אשכולות בלקוח:

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

isServiceAvailable

ה-API הזה משמש כדי לבדוק אם השירות זמין לשילוב ואם אפשר להציג את התוכן במכשיר.

ל-Engage SDK מגרסה 1.6.0 ואילך (מומלץ)

android skills add engage-sdk-integration

Use the engage-sdk-integration skill to use Engage SDK 1.6.0 and refactor isServiceAvailable to pass ServiceAvailabilityRequest for publishing all cluster types.

אתם יכולים לבדוק את זמינות השירות לכל סוג אשכול שאתם מתכוונים לפרסם. ‫isServiceAvailable API מקבל אובייקט בקשה, ServiceAvailabilityRequest, שמכיל את סוגי האשכולות שצריך לבדוק את זמינות השירות שלהם. בטבלה הבאה מפורטים ערכי ה-enum של ClusterType שנדרשים ל-ServiceAvailabilityRequest.

val request = ServiceAvailabilityRequest.Builder()
    .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
    .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
    .build()

client.isServiceAvailable(request).addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val availabilityMap = task.result
        if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
            // Proceed with publishing continuation content
        }
        if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
}

ServiceAvailabilityRequest request =
    new ServiceAvailabilityRequest.Builder()
        .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
        .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
        .build();

client.isServiceAvailable(request).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        Map<Integer, Boolean> availabilityMap = task.getResult();
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
            // Proceed with publishing continuation content
        }
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
});

תכונה: זמינות מותנית של שירותים

חלק מהאפליקציות המשולבות מבקשות הגדרה מיוחדת שמפעילה ומשביתה את שירות Engage לסירוגין כדי להפחית את עלויות ההצגה. עם זאת, אסטרטגיית ניתוח התוכן לסירוגין משפיעה לרעה על חוויית המשתמש: תוכן מיושן לא יוצג, וחלק מהפלטפורמות לא יציגו תוכן.

החל מגרסה 1.6.0, Engage SDK מאפשר לבדוק את הזמינות של סוגי אשכולות ספציפיים. אם אתם רוצים להצטרף לתכונה הזו בכל סוג של אשכול, פנו אל engage-developers@google.com.

לגרסאות SDK שקדמו לגרסה 1.6.0 (הוצאה משימוש)

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

אם מסיבה עסקית פנימית כלשהי אף אחד מהאשכולות לא פורסם, אנחנו ממליצים מאוד לעדכן את סטטוס הפרסום באמצעות ה-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.

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

deleteRecommendationsClusters

ה-API הזה משמש למחיקת התוכן של אשכולות ההמלצות.

client.deleteRecommendationsClusters()

client.deleteRecommendationsClusters();

כשהשירות מקבל את הבקשה, הוא מסיר את הנתונים הקיימים מאשכולות ההמלצות. אם יש שגיאה, כל הבקשה נדחית והמצב הקיים נשמר.

deleteUserManagementCluster

ה-API הזה משמש למחיקת התוכן של אשכול UserAccountManagement.

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

כשהשירות מקבל את הבקשה, הוא מסיר את הנתונים הקיימים מהאשכול UserAccountManagement. אם יש שגיאה, כל הבקשה נדחית והמצב הקיים נשמר.

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: טיפול בכוונות שידור

בנוסף לביצוע קריאות ל-API לפרסום תוכן באמצעות משימה, צריך גם להגדיר BroadcastReceiver כדי לקבל את הבקשה לפרסום תוכן.

המטרה של כוונות שידור היא בעיקר להפעיל מחדש את האפליקציה ולאלץ סנכרון נתונים. כוונות שידור לא נועדו להישלח בתדירות גבוהה מאוד. הוא מופעל רק כששירות Engage קובע שהתוכן עשוי להיות לא עדכני (לדוגמה, בן שבוע). כך אפשר להיות בטוחים יותר שהמשתמש יקבל חוויית תוכן עדכנית, גם אם האפליקציה לא הופעלה במשך זמן רב.

צריך להגדיר את BroadcastReceiver בשתי הדרכים הבאות:

• רושמים באופן דינמי מופע של המחלקה BroadcastReceiver באמצעות Context.registerReceiver(). ההרשאה הזו מאפשרת תקשורת מאפליקציות שעדיין פועלות בזיכרון.

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

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),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);
}

• מצהירים באופן סטטי על הטמעה באמצעות התג <receiver> בקובץ AndroidManifest.xml. ההרשאה הזו מאפשרת לאפליקציה לקבל כוונות שידור כשהיא לא פועלת, וגם לפרסם את התוכן.

<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>
   </receiver>
</application>

השירות ישלח את הכוונות הבאות:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION מומלץ להתחיל שיחת publishRecommendationClusters כשמקבלים את ה-intent הזה.

תהליך עבודה של שילוב

למדריך מפורט על אימות השילוב אחרי שהוא הושלם, ראו תהליך העבודה של מפתחים לשילוב עם Engage.

שאלות נפוצות

שאלות נפוצות לגבי Engage SDK

יצירת קשר

אם יש לכם שאלות במהלך תהליך השילוב, אתם יכולים לפנות אל engage-developers@google.com. הצוות שלנו ישיב בהקדם האפשרי.

השלבים הבאים

אחרי שתשלימו את השילוב, אלה השלבים הבאים:

• שולחים אימייל לכתובת engage-developers@google.com ומצרפים את קובץ ה-APK המשולב שמוכן לבדיקה על ידי Google.
• ‫Google מבצעת אימות ובדיקות פנימיות כדי לוודא שהשילוב פועל כצפוי. אם צריך לבצע שינויים, Google תפנה אליכם עם הפרטים הנדרשים.
• כשהבדיקה מסתיימת ולא נדרשים שינויים, Google יוצרת איתכם קשר כדי להודיע לכם שאתם יכולים להתחיל לפרסם את ה-APK המעודכן והמשולב בחנות Play.
• אחרי ש-Google תאשר שקובץ ה-APK המעודכן פורסם בחנות Play, אשכולות ההמלצות יפורסמו ויוצגו למשתמשים.