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

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

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

פרטי השילוב

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

טרמינולוגיה

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

ההמלצות מופיעות במבנה הבא:

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

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

• 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.5.2'
}

סיכום

התכנון מבוסס על הטמעה של שירות קשור.

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

שלב 1: מספקים נתוני ישות

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

1. PortraitMediaEntity
2. SocialPostEntity

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

PortraitMediaEntity

SocialPostEntity

מפרט לתמונות

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

פורמטים של קבצים

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

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

‎5,120 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

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

deleteRecommendationClusters

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

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

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

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

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

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

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

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

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

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

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

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

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

שאלות נפוצות

שאלות נפוצות על Engage SDK

יצירת קשר

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

השלבים הבאים

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

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