Engage SDK Social: instrukcje integracji technicznej firm zewnętrznych

Google tworzy na urządzeniu platformę, która porządkuje aplikacje według branż i umożliwia korzystanie ze spersonalizowanych treści w aplikacji. i odkrywania. Dzięki temu partnerzy mogą mają możliwość zaprezentowania swoich najlepszych, bogatych materiałów na specjalnym kanale do aplikacji.

Ten dokument zawiera instrukcje dla deweloperów dotyczące integrowania do publikowania treści społecznościowych za pomocą pakietu Engage SDK.

Szczegóły integracji

W następnej sekcji znajdziesz szczegóły integracji.

Terminologia

Klastry rekomendacji pokazują spersonalizowane sugestie od poszczególnych użytkowników partnera w programie.

Rekomendacje mają następującą strukturę:

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

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

• PortraitMediaEntity
• Element społecznościowy

PortraitMediaEntity musi zawierać jeden obraz w orientacji pionowej. Profil Metadane dotyczące interakcji są opcjonalne.

• Post

  • obraz w trybie pionowym i sygnatura czasowa,
  • Obraz w orientacji pionowej + tekst i sygnatura czasowa

• Profil

  • Awatar, imię i nazwisko lub nick, dodatkowe zdjęcie

• Interakcja

  • Tylko liczba i etykieta lub
  • Liczba i elementy wizualne (ikona)

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

• Profil

  • Awatar, imię i nazwisko lub nick, dodatkowy tekst, dodatkowe zdjęcie

• Post

  • tekst i sygnatura czasowa,
  • Rich media (obraz lub URL reklamy multimedialnej) i sygnatura czasowa lub
  • tekst i multimedia (obraz lub URL sformatowany) oraz sygnatura czasowa lub
  • Podgląd filmu (miniatura i czas trwania) oraz sygnatura czasowa

• Interakcje

  • Liczba tylko etykieta lub
  • Liczba wizualny (ikona)

Przygotowanie

Minimalny poziom interfejsu API: 19

Dodaj bibliotekę com.google.android.engage:engage-core 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.5.2'
}

Podsumowanie

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

Dane, które klient może publikować, podlegają następującym limitom dla różnych typy klastrów:

Krok 1. Podaj dane encji

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

1. PortraitMediaEntity
2. SocialPostEntity

Poniższe tabele przedstawiają dostępne atrybuty i wymagania dla każdego z nich.

PortraitMediaEntity

SocialPostEntity

Specyfikacja obrazu

Obrazy muszą być hostowane w publicznych sieciach CDN, aby Google miał dostęp do nich .

Formaty plików

PNG, JPG, statyczny GIF, WebP

Maksymalny rozmiar pliku

5120 KB

Dodatkowe rekomendacje

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

Krok 2. Podaj dane klastra

Zaleca się, aby zadanie publikowania treści było wykonywane w tle (na przykład WorkManager). i zaplanowano je regularnie lub według konkretnego wydarzenia (np. za każdym razem, użytkownik uruchomił aplikację lub zaczął obserwować nowe konto).

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 oraz czy treść może być prezentowana 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 obiektów RecommendationCluster na liście.

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 jedna transakcja:

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

W przypadku błędu całe żądanie zostaje odrzucone, a obecny stan to i utrzymywane informacje.

publishUserAccountManagementRequest

Ten interfejs API służy do publikowania karty logowania . Działanie związane z logowaniem kieruje użytkowników do stronie logowania, tak by aplikacja mogła publikować treści (lub udostępniać treści spersonalizowanej)

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 jedna transakcja:

• Dotychczasowe dane UserAccountManagementCluster od partnera dewelopera są usunięto.
• Dane z żądania są analizowane i przechowywane w zaktualizowanym Klaster zarządzania kontami użytkowników.

W przypadku błędu całe żądanie zostaje odrzucone, a obecny stan to i utrzymywane informacje.

updatePublishStatus

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

• Podawanie stanu we wszystkich sytuacjach, nawet po opublikowaniu treści (STATUS == PUBLISHED) – ma kluczowe znaczenie przy wypełnianiu paneli, które używają jawny stan, który przekazuje informacje o stanie i inne wskaźniki integracji.
• Jeśli treści nie zostały opublikowane, ale stan integracji nie jest nieprawidłowy (STATUS == NOT_PUBLISHED), Google może uniknąć wywoływania alertów w aplikacji paneli stanu. Potwierdza ono, że treść nie została opublikowana z powodu jest oczekiwana z punktu widzenia dostawcy.
• Pomaga deweloperom 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 czynności aby wyświetlić jej zawartość lub ją pokonać.

Lista kodów stanu odpowiednich 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 z powodu niezalogowanego użytkownika, Zalecamy opublikowanie karty logowania. Jeśli z jakiegoś powodu dostawcy nie mogą opublikować karty logowania zalecamy wywoływanie interfejsu API updatePublishStatus z kodem stanu 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

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

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

Gdy usługa otrzyma żądanie, usuwa istniejące dane z Klastry rekomendacji. W przypadku błędu żądanie zostaje odrzucone w całości. a obecny stan zostaje zachowany.

deleteUserManagementCluster

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

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

Gdy usługa otrzyma żądanie, usuwa istniejące dane z Klaster zarządzania kontami użytkowników. W przypadku błędu całe żądanie jest odrzucono i zachowany zostanie obecny stan.

deleteClusters

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

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

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

Gdy usługa otrzyma żądanie, usuwa istniejące dane ze wszystkich klastrów pasujących do określonych typów klastrów. Klienci mogą wybrać, czy chcą pozytywnie ocenić dla wielu typów klastrów. W przypadku błędu całe żądanie jest odrzucane, obecny stan zostaje zachowany.

Obsługa błędów

Zdecydowanie zalecamy wsłuchiwanie się w wyniki zadania z interfejsów API do publikowania, takich jak że można podjąć działania, aby odzyskać i ponownie przesłać udane zadanie.

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 z przyczyną podaną w atrybucie .

Krok 3. Obsługa intencji transmisji

Oprócz wykonywania wywołań interfejsu Content API w zadaniu wymagane do skonfigurowania BroadcastReceiver do otrzymania z prośbą o opublikowanie treści.

Celem intencji transmisji jest głównie ponowna aktywacja aplikacji i wymuszenie użycia danych synchronizację. Intencje związane z transmisją nie są przeznaczone do wysyłania zbyt często. Jest tylko uruchamianych, gdy usługa dla Agencji ustali, że zawartość może być nieaktualna (w przypadku np. tydzień). Dzięki temu będzie miała większą pewność, i otwierać nowe treści, nawet jeśli aplikacja nie była uruchamiana przez bardzo długi okres.

BroadcastReceiver trzeba skonfigurować na 2 sposoby:

• Dynamicznie zarejestruj instancję klasy BroadcastReceiver za pomocą Context.registerReceiver() Umożliwia to komunikację z aplikacji które wciąż są żywe 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 deklaruj implementację z tagiem <receiver> w sekcji AndroidManifest.xml. Zezwala to aplikacji na odbieranie komunikatów intencje, gdy nie jest uruchomiona, oraz umożliwia publikowanie aplikacji 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>

Sprzedawca otrzyma te zamiary, usługa:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION Zalecane jest rozpoczęcie połączenia publishRecommendationClusters, gdy w odpowiedzi na żądania użytkowników.

Proces integracji

Szczegółowy przewodnik dotyczący weryfikacji integracji po jej zakończeniu znajdziesz na stronie Przepływ pracy w zakresie integracji dla programistów

Najczęstsze pytania

Przeczytaj Najczęstsze pytania o pakiet SDK dla Agencji dotyczące: Najczęstsze pytania

Kontakt

Kontakt Engage-developers@google.com, jeśli są na ewentualne pytania w trakcie procesu integracji. Nasz zespół udzieli odpowiedzi jak to tylko możliwe.

Dalsze kroki

Po zakończeniu integracji należy wykonać następujące czynności:

• Wyślij e-maila do engagement-developers@google.com i załącz zintegrowany pakiet APK gotowy do testowania przez Google.
• Google przeprowadza wewnętrzną weryfikację i weryfikację, aby upewnić się, że jej integracja działa zgodnie z oczekiwaniami. Jeśli potrzebne będą zmiany, Google skontaktuje się z Tobą z niezbędnymi informacjami.
• Gdy testy zostaną zakończone i nie trzeba będzie wprowadzać żadnych zmian, Google skontaktuje się z Tobą w sprawie: powiadomi Cię, że możesz rozpocząć publikowanie zaktualizowanego i zintegrowanego pliku APK w Sklep Play.
• Gdy Google potwierdzi, że zaktualizowany pakiet APK został opublikowany w Sklep Play, Twoja rekomendacja, klastry zostaną opublikowane i widoczne dla: użytkowników.