Engage SDK Social: instrukcje integracji technicznej firm zewnętrznych

Google tworzy platformę na urządzeniu, która porządkuje aplikacje użytkowników według kategorii i zapewnia nowe, atrakcyjne możliwości związane z oglądaniem i odkrywaniem treści aplikacji w spersonalizowany sposób. Dzięki tej funkcji partnerzy mogą prezentować swoje najlepsze treści w specjalnym kanale poza aplikacją.

Ten dokument zawiera instrukcje dla deweloperów, którzy chcą zintegrować swoje treści społecznościowe z wykorzystaniem pakietu SDK dla Agencji za pomocą pakietu SDK dla deweloperów, który wypełni ten nowy obszar.

Szczegóły integracji

W poniższej sekcji znajdziesz szczegóły integracji.

Terminologia

Klastry rekomendacji wyświetlają spersonalizowane sugestie od poszczególnych partnerów deweloperów.

Rekomendacje mają taką strukturę:

Klaster rekomendacji: widok interfejsu zawierający grupę rekomendacji od tego samego partnera programistycznego.

Każdy klaster rekomendacji składa się z jednego z tych 2 typów elementów :

• Portret MediaEntity
• SocialPostEntity

PortreMediaEntity musi zawierać 1 obraz w orientacji pionowej do posta. Metadane związane z profilem i interakcjami są opcjonalne.

• Post

  • obraz w trybie pionowym i sygnatura czasowa;
  • Obraz w trybie pionowym + zawartość tekstowa i sygnatura czasowa

• Profil

  • Awatar, nazwa lub nick, dodatkowe zdjęcie

• Interakcja

  • tylko licznik i etykieta,
  • Licznik i element graficzny (ikona)

SocialPostEntity zawiera metadane związane z profilem, postem i interakcją.

• Profil

  • Awatar, nazwa lub nick, dodatkowy tekst, dodatkowe zdjęcie

• Post

  • tekst i sygnatura czasowa;
  • Rich media (adres URL obrazu lub adresu URL sformatowanego) i sygnatura czasowa;
  • Tekst i multimedia (adres URL obrazu lub sformatowanego adresu URL) oraz sygnatura czasowa

• Interakcje

  • Tylko liczenie i etykieta lub
  • Liczba i element graficzny (ikona)

Przygotowanie

Minimalny poziom interfejsu API: 19

Dodaj bibliotekę com.google.android.play:engage do aplikacji:

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

Podsumowanie

Projekt opiera się na implementacji powiązanej usługi.

Dane, które klient może publikować, podlegają tym ograniczeniom w przypadku różnych typów klastrów:

Krok 1. Podaj dane encji

Pakiet SDK ma zdefiniowane różne elementy reprezentujące każdy typ elementu. Pakiet SDK obsługuje w kategorii Społecznościowe te elementy:

1. PortraitMediaEntity
2. SocialPostEntity

W tabelach poniżej znajdziesz dostępne atrybuty i wymagania dla poszczególnych typów.

PortraitMediaEntity

SocialPostEntity

Specyfikacja obrazu

Obrazy muszą być hostowane w publicznych sieciach CDN, aby umożliwić Google dostęp do nich.

Formaty plików

PNG, JPG, statyczne pliki GIF, WebP

Maksymalny rozmiar pliku

5120 KB

Dodatkowe zalecenia

• Bezpieczny obszar obrazu: ważne treści umieść w środkowych 80% obrazu.
• Użyj przezroczystego tła, aby obraz był poprawnie wyświetlany w ustawieniach ciemnego i jasnego motywu.

Krok 2. Podaj dane klastra

Zalecamy, aby zadanie publikowania treści było wykonywane w tle (np. za pomocą WorkManagera) i planowane regularnie lub na podstawie zdarzeń (np. za każdym razem, gdy użytkownik otworzy aplikację lub gdy tylko wykona działanie na nowym koncie).

Za publikowanie klastrów społecznościowych odpowiada AppEngageSocialClient.

Istnieją następujące interfejsy API do publikowania klastrów w kliencie:

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

isServiceAvailable

Ten interfejs API służy do sprawdzania, czy usługa jest dostępna do integracji i czy treści można zaprezentować na urządzeniu.

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

Ten interfejs API służy do publikowania listy obiektów RecommendationCluster.

Obiekt RecommendationCluster może mieć te atrybuty:

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

Gdy usługa otrzyma żądanie, w ramach jednej transakcji wykonywane są te działania:

• Wszystkie istniejące dane klastra rekomendacji zostaną usunięte.
• Dane z żądania są analizowane i przechowywane w nowych klastrach rekomendacji.

W przypadku błędu całe żądanie jest odrzucane, a istniejący stan zostaje zachowany.

publishUserAccountManagementRequest

Ten interfejs API służy do publikowania karty logowania . Użytkownicy są kierowani na stronę logowania w aplikacji, na której mogą publikować treści (lub udostępniać im bardziej spersonalizowane treści).

Te metadane są częścią karty logowania –

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

Gdy usługa otrzyma żądanie, w ramach jednej transakcji wykonywane są te działania:

• Dotychczasowe dane UserAccountManagementCluster od partnera dewelopera zostaną usunięte.
• Dane z żądania są analizowane i przechowywane w zaktualizowanym klastrze UserAccountManagementCluster.

W przypadku błędu całe żądanie jest odrzucane, a istniejący stan zostaje zachowany.

updatePublishStatus

Jeśli z jakichkolwiek wewnętrznych powodów biznesowych nie zostanie opublikowany żaden z klastrów, zdecydowanie zalecamy zaktualizowanie stanu publikacji za pomocą interfejsu API updatePublishStatus. To ważne, ponieważ :

• Podanie stanu we wszystkich scenariuszach, nawet po opublikowaniu treści (STAN == OPUBLIKOWANO), ma kluczowe znaczenie przy wypełnianiu paneli, które korzystają z tego jednoznacznego stanu do przekazywania informacji o stanie i innych wskaźnikach integracji.
• Jeśli treści nie są opublikowane, ale stan integracji nie jest uszkodzony (STATUS == NOT_OpublikujED), Google może uniknąć aktywowania alertów w panelach stanu aplikacji. Jest to potwierdzenie, że treści nie zostały opublikowane z powodu oczekiwanej sytuacji z punktu widzenia dostawcy.
• Dzięki temu deweloperzy mogą określić, kiedy dane są publikowane, a kiedy nie.
• Google może używać kodów stanu, aby skłonić użytkownika do wykonania określonych działań w aplikacji, co pozwoli mu zobaczyć zawartość aplikacji lub ją przezwyciężyć.

Lista kodów stanu kwalifikującego się do publikacji :

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

Jeśli treści nie zostały opublikowane, ponieważ użytkownik nie jest zalogowany, zalecamy opublikowanie karty logowania. Jeśli z jakiegoś powodu dostawcy nie mogą opublikować karty logowania, zalecamy wywołanie interfejsu API updatePublishStatus z kodem stanu NOT_OpublikujED_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

Ten interfejs API służy do usuwania zawartości klastrów rekomendacji.

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

Gdy usługa otrzyma żądanie, usunie istniejące dane z klastrów rekomendacji. W przypadku błędu całe żądanie jest odrzucane, a obecny stan zostaje zachowany.

deleteUserManagementCluster

Ten interfejs API służy do usuwania zawartości klastra UserAccountManagement.

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

Po otrzymaniu żądania usługa usuwa istniejące dane z klastra UserAccountManagement. W przypadku błędu całe żądanie jest odrzucane, a bieżący stan zostaje zachowany.

deleteClusters

Ten interfejs API służy do usuwania treści określonego typu klastra.

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

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

Gdy usługa otrzymuje żądanie, usuwa istniejące dane ze wszystkich klastrów pasujących do określonych typów klastrów. Klienty mogą przekazywać 1 lub wiele typów klastrów. W przypadku błędu całe żądanie jest odrzucane, a obecny stan zostaje zachowany.

Obsługa błędów

Zdecydowanie zalecamy wsłuchiwanie się w wynik zadania z interfejsów API publikowania, aby można było podjąć dalsze działania w celu odzyskania udanego zadania i ponownego przesłania go.

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

Błąd jest zwracany jako AppEngageException, a przyczyna jest podana w postaci kodu błędu.

Krok 3. Obsługuj intencje transmisji

Oprócz wykonywania wywołań interfejsu Content API w zadaniu musisz też skonfigurować BroadcastReceiver, aby odbierać żądanie opublikowania treści.

Intencje dotyczące przesyłania służą głównie do reaktywacji aplikacji i wymuszania synchronizacji danych. Intencje transmisji nie są przeznaczone do wysyłania zbyt często. Jest wywoływane tylko wtedy, gdy usługa dla Agencji stwierdzi, że treści mogą być nieaktualne (np. sprzed tygodnia). Dzięki temu zyska on większą pewność, że użytkownik będzie mógł korzystać z nowych treści, nawet jeśli aplikacja nie była uruchamiana od dłuższego czasu.

BroadcastReceiver należy skonfigurować na dwa sposoby:

• Dynamicznie zarejestruj instancję klasy BroadcastReceiver za pomocą Context.registerReceiver(). Umożliwia to komunikację z aplikacji, które wciąż są zapisane w pamięci.

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

}

• Statycznie zadeklaruj implementację za pomocą tagu <receiver> w pliku AndroidManifest.xml. Dzięki temu aplikacja może odbierać komunikaty, gdy nie jest uruchomiona, oraz publikować treści.

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

Usługa będzie wysyłać te zamiary:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION Zalecamy uruchomienie wywołania publishRecommendationClusters przy odbieraniu tej intencji.

Przepływ pracy w integracji

Szczegółowy przewodnik dotyczący weryfikowania integracji po jej zakończeniu znajdziesz w artykule o procesie integracji programistycznej Google Workspace.

Najczęstsze pytania

Zapoznaj się z odpowiedziami na najczęstsze pytania dotyczące pakietu SDK dla Agencji.

Kontakt

Jeśli masz pytania dotyczące procesu integracji, wyślij e-maila na adres engagement-developers@google.com. Nasz zespół odpowie tak szybko, jak to będzie możliwe.

Dalsze kroki

Po zakończeniu integracji wykonaj te czynności:

• Wyślij e-maila na adres Engage-developers@google.com i załącz zintegrowany pakiet APK, który jest gotowy do przetestowania przez Google.
• Google przeprowadza weryfikację i weryfikację wewnętrzną, aby mieć pewność, że integracja działa zgodnie z oczekiwaniami. Jeśli potrzebne będą zmiany, Google skontaktuje się z Tobą, aby przekazać Ci niezbędne informacje.
• Gdy testy zostaną ukończone i nie będą wymagane żadne zmiany, Google skontaktuje się z Tobą, aby powiadomić Cię, że możesz rozpocząć publikowanie zaktualizowanego i zintegrowanego pakietu APK w Sklepie Play.
• Gdy Google potwierdzi, że zaktualizowany plik APK zostanie opublikowany w Sklepie Play, Twoje rekomendacje zostaną opublikowane i będą widoczne dla użytkowników.