Engage SDK Social: instrukcje integracji technicznej firm zewnętrznych

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Google tworzy interfejs na urządzeniu, który porządkuje aplikacje użytkowników według branży i umożliwia nowe wciągające wrażenia podczas przeglądania i odtwarzania spersonalizowanych treści w aplikacji. Dzięki temu partnerzy deweloperzy mogą prezentować swoje najlepsze treści w ramach dedykowanego kanału poza aplikacją.

Ten dokument zawiera instrukcje dla partnerów deweloperów dotyczące integracji treści społecznościowych za pomocą pakietu Engage SDK w celu wypełniania nowej powierzchni.

Szczegóły integracji

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

Terminologia

Rekomendacje to grupy zawierające spersonalizowane sugestie od poszczególnych partnerów deweloperów.

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

Klaster rekomendacji: widok interfejsu użytkownika zawierający grupę rekomendacji od tego samego partnera deweloperskiego.

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

• PortraitMediaEntity
• SocialPostEntity

PortraitMediaEntity musi zawierać 1 obraz w orientacji pionowej dla posta. Metadane dotyczące profilu i interakcji są opcjonalne.

• Post

  • obraz w orientacji pionowej i stempel czasu,
  • Obraz w formacie pionowym + treść tekstowa i sygnatura czasowa

• Profil

  • Avatar, Name or Handle, Additional image

• Interakcje

  • tylko zliczanie i etykietowanie,
  • Liczba i wizualizacja (ikona)

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

• Profil

  • Avatar, imię lub nick, dodatkowy tekst, dodatkowy obraz

• Post

  • Tekst i sygnatura czasowa lub
  • multimedia (obraz lub adres URL multimedialny) i sygnatura czasowa,
  • tekst i multimedia (obraz lub adres URL multimedialny) oraz sygnatura czasowa,
  • Podgląd filmu (miniatura i czas trwania) oraz sygnatura czasowa

• Interakcje

  • Zliczaj i tylko etykietuj lub
  • Liczba i wizualizacja (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 jest oparty na implementacji usługi z ograniczeniami.

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

Krok 1. Podaj dane o podmiocie

Pakiet SDK definiuje różne elementy reprezentujące poszczególne typy elementów. W ramach kategorii „Social” pakiet SDK obsługuje te elementy:

1. PortraitMediaEntity
2. SocialPostEntity

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

PortraitMediaEntity

SocialPostEntity

Specyfikacja obrazu

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

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% obrazu.
• Użyj przezroczystego tła, aby obraz był prawidłowo wyświetlany w ustawieniach motywu ciemnego i jasnego.

Krok 2. Podaj dane klastra

Zalecamy, aby zadanie publikowania treści było wykonywane w tle (np. za pomocą WorkManagera) i planowane regularnie lub w reakcji na zdarzenie (np. za każdym razem, gdy użytkownik otworzy aplikację lub gdy zacznie obserwować nowe konto).

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

Do publikowania klastrów w kliencie służą te interfejsy API:

• 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 można wyświetlić treści 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 wykona te działania:

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

W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.

publishUserAccountManagementRequest

Ten interfejs API służy do publikowania karty logowania . Działanie logowania kieruje użytkowników na stronę logowania w aplikacji, aby aplikacja mogła publikować treści (lub udostępniać 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 wykona 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ła prośba jest odrzucana, a obecny stan jest zachowany.

updatePublishStatus

Jeśli z jakiegokolwiek wewnętrznego powodu biznesowego żaden z tych klastrów nie został opublikowany, zdecydowanie zalecamy zaktualizowanie stanu publikacji za pomocą interfejsu updatePublishStatus API. Jest to ważne, ponieważ :

• Podanie stanu we wszystkich scenariuszach, nawet gdy treści są opublikowane (STATUS = PUBLISHED), jest kluczowe dla wypełniania paneli, które używają tego stanu do przekazywania informacji o stanie i innych danych dotyczących integracji.
• Jeśli nie ma opublikowanych treści, ale integracja nie jest uszkodzona (STATUS = NOT_PUBLISHED), Google może nie uruchamiać alertów na panelach danych dotyczących zdrowia w aplikacji. Potwierdza, że treści nie są publikowane z powodu oczekiwanego stanu z punktu widzenia dostawcy.
• Pomaga deweloperom udostępniać informacje o tym, kiedy dane są publikowane, a kiedy nie.
• Google może używać kodów stanu, aby zachęcić użytkownika do wykonania określonych działań w aplikacji, dzięki którym będzie on mógł zobaczyć jej zawartość lub ją pokonać.

Lista kodów stanu publikacji, które kwalifikują się do wyświetlania :

// 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 są publikowane, ponieważ użytkownik nie jest zalogowany, Google zaleca opublikowanie karty logowania. Jeśli z jakiegokolwiek powodu dostawcy nie mogą opublikować karty logowania, zalecamy wywołanie 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 treści z grup rekomendacji.

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

Gdy usługa otrzyma prośbę, usunie istniejące dane z klastrów rekomendacji. W przypadku błędu cała prośba zostaje odrzucona, a istniejący stan jest zachowany.

deleteUserManagementCluster

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

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

Gdy usługa otrzyma żądanie, usuwa istniejące dane z klastra UserAccountManagement. W przypadku błędu cała prośba jest odrzucana, a obecny stan jest zachowany.

deleteClusters

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

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

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

Gdy usługa otrzyma żądanie, usunie istniejące dane ze wszystkich klastrów pasujących do określonych typów klastrów. Klienci mogą przekazywać jeden lub wiele typów klastrów. W przypadku błędu cała prośba jest odrzucana, a istniejący stan jest zachowany.

Obsługa błędów

Zdecydowanie zalecamy odsłuchanie wyniku zadania z interfejsów API do publikowania, aby można było podjąć dalsze działania w celu odzyskania i ponowniego przesłania zadania, które zostało wykonane prawidłowo.

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 jego przyczyna jest podana w postaci kodu błędu.

Krok 3. Obsługa intencji przesyłania

Oprócz wywoływania interfejsu Content API za pomocą zadania musisz też skonfigurować BroadcastReceiver, aby odbierać prośby o publikowanie treści.

Intencje przesyłania są przeznaczone głównie do ponownej aktywacji aplikacji i wymuszania synchronizacji danych. Intencje dotyczące transmisji nie są przeznaczone do wysyłania zbyt często. Jest ona wywoływana tylko wtedy, gdy usługa Engage stwierdzi, że treści mogą być nieaktualne (np. mają tydzień). Dzięki temu użytkownik ma pewność, że będzie mieć dostęp do aktualnych treści, nawet jeśli aplikacja nie była uruchamiana przez długi czas.

Element BroadcastReceiver musi być skonfigurowany w jednym z tych 2 sposobów:

• Dynamicznie zarejestruj instancję klasy BroadcastReceiver za pomocą funkcji Context.registerReceiver(). Umożliwia to komunikację z aplikacji, które są nadal aktywne 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));

}

• Zadeklaruj statycznie implementację za pomocą tagu <receiver> w pliku AndroidManifest.xml. Dzięki temu aplikacja może odbierać intencje przesyłania, gdy nie jest uruchomiona, a także 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 wyśle te intencje:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION W przypadku tej intencji zalecamy rozpoczęcie rozmowy publishRecommendationClusters.

Proces integracji

Szczegółowy przewodnik po weryfikacji integracji po jej zakończeniu znajdziesz w artykule Proces integracji z Engage dla deweloperów.

Najczęstsze pytania

Najczęstsze pytania dotyczące Engage SDK znajdziesz w artykule Najczęstsze pytania dotyczące Engage SDK.

Kontakt

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

Dalsze kroki

Po zakończeniu tej 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 sprawdza integrację wewnętrznie, aby upewnić się, że działa ona zgodnie z oczekiwaniami. Jeśli będą potrzebne zmiany, Google skontaktuje się z Tobą, podając niezbędne informacje.
• Gdy testy zostaną zakończone i nie trzeba będzie wprowadzać żadnych zmian, skontaktujemy się z Tobą, aby poinformować, że możesz rozpocząć publikowanie zaktualizowanego i zintegrowanego pliku APK w Sklepie Play.
• Gdy Google potwierdzi, że zaktualizowany plik APK został opublikowany w Sklepie Play, Twoje rekomendacje i ich grupy zostaną opublikowane i staną się widoczne dla użytkowników.