Tworzenie transakcji cyfrowych niezużywalnych (Dialogflow)

Z tego przewodnika dowiesz się, jak dodać transakcje cyfrowe do akcji konwersacyjnej, aby użytkownicy mogli kupować Twoje niezużywalne produkty cyfrowe.

Kluczowe terminy: niezużywany towar cyfrowy to jednostka magazynowa (SKU), którą można kupić tylko raz. Oznacza to na przykład płatny dostęp do dodatkowych treści w aplikacji Action lub na Androida. Ten rodzaj produktu różni się od konsumpcyjnego towaru cyfrowego, który można kupić, wykorzystać i ponownie zakupić.

Więcej informacji o nieużywanych jednorazowych produktach znajdziesz w dokumentacji Androida na temat jednorazowych funkcji poszczególnych usług.

Ograniczenia i wytyczne dotyczące sprawdzania

W przypadku akcji z transakcjami obowiązują dodatkowe zasady. Sprawdzenie działań, które obejmują transakcje, może nam zająć kilka tygodni, więc uwzględnij ten czas przy planowaniu harmonogramu publikacji. Aby ułatwić proces sprawdzania, przed przesłaniem akcji do sprawdzenia upewnij się, że przestrzegasz zasad i wytycznych dotyczących transakcji.

Akcje, które służą do sprzedaży produktów cyfrowych, można wdrażać tylko w tych krajach:

  • Australia
  • Brazylia
  • Kanada
  • Indonezja
  • Japonia
  • Meksyk
  • Rosja
  • Singapur
  • Tajlandia
  • Turcja
  • Wielka Brytania
  • Stany Zjednoczone

Przepływ transakcji

W tym przewodniku opisujemy wszystkie etapy procesu tworzenia produktów cyfrowych. Akcja obsługuje transakcje dotyczące produktów cyfrowych w następujący sposób:

  1. Skonfiguruj klienta interfejsu API zakupów cyfrowych: akcja używa interfejsu API zakupów cyfrowych do komunikacji z zasobami reklamowymi Google Play i transakcjami. Zanim akcja podejmie jakiekolwiek inne działania, tworzy klienta JWT z kluczem usługi do komunikacji z interfejsem API zakupów cyfrowych.
  2. Zbieranie informacji: akcja zbiera podstawowe informacje o użytkowniku i Twoich zasobach reklamowych Google Play, aby przygotować się do transakcji.
    1. Weryfikowanie wymagań dotyczących transakcji: akcja korzysta z Asystenta wymagań dotyczących transakcji cyfrowych na początku procesu zakupu, aby upewnić się, że użytkownik może dokonać transakcji.
    2. Zbieranie dostępnych zasobów reklamowych: akcja sprawdza zasoby reklamowe Google Play i identyfikuje produkty, które są obecnie dostępne do zakupu.
  3. Utwórz zamówienie: akcja prezentuje użytkownikowi dostępne produkty cyfrowe, aby mógł je wybrać.
  4. Sfinalizuj zakup: akcja używa interfejsu API zakupów cyfrowych do zainicjowania zakupu wybranego przez użytkownika w Sklepie Google Play.
  5. Przetwórz wynik: akcja otrzymuje kod stanu transakcji i powiadamia użytkownika, że zakup się udał (lub wymaga wykonania dodatkowych czynności).

Wymagania wstępne

Zanim włączysz transakcje cyfrowe do akcji, musisz spełnić te wymagania wstępne:

Powiąż aplikację na Androida

Jeśli nie masz obecnie aplikacji na Androida z uprawnieniami do płatności w Konsoli Google Play, wykonaj te czynności:

  1. Utwórz nowy projekt w Android Studio lub w wybranym IDE Androida. Wybierz opcje w promptach konfiguracji projektu, aby utworzyć bardzo podstawową aplikację.
  2. Nadaj projektowi nazwę pakietu, np. com.mycompany.myapp. Nie pozostawiaj tej nazwy domyślnej, ponieważ w Konsoli Play nie będzie można przesyłać pakietów zawierających com.example.
  3. Otwórz plik AndroidManifest.xml aplikacji.
  4. Dodaj ten wiersz kodu w elemencie manifest:

    <uses-permission android:name="com.android.vending.BILLING" />

    Plik AndroidManifest.xml powinien wyglądać jak ten blok kodu:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="com.mycompany.myapp">
        <uses-permission android:name="com.android.vending.BILLING" />
    
        <application
            android:allowBackup="true"
            android:icon="@mipmap/ic_launcher"
            android:label="@string/app_name"
            android:roundIcon="@mipmap/ic_launcher_round"
            android:supportsRtl="true"
            android:theme="@style/AppTheme" />
    </manifest>
    
  5. Utwórz aplikację jako podpisany plik APK. W Android Studio wykonaj te czynności:

    1. Kliknij Build (Utwórz), Wygeneruj podpisany pakiet / plik APK.
    2. Kliknij Dalej.
    3. W sekcji Ścieżka magazynu kluczy kliknij Utwórz nowy.
    4. Wypełnij każde pole, a potem kliknij OK. Zapisz sobie hasło do magazynu kluczy i hasło klucza i zapisz je w bezpiecznym miejscu, bo będziesz ich później potrzebować.
    5. Kliknij Dalej.
    6. Wybierz release.
    7. Wybierz V1 (podpis JAR).
    8. Kliknij Zakończ.
    9. Po kilku sekundach Android Studio wygeneruje plik app-release.apk. Znajdź ten plik do późniejszego użycia.
  6. Utwórz nową aplikację w Konsoli Google Play.

  7. Przejdź do sekcji Wersje aplikacji.

  8. W sekcji Ścieżki zamknięte kliknij Zarządzaj, a następnie Alfa.

  9. Kliknij przycisk Utwórz wersję.

  10. W sekcji Pozwól Google zarządzać Twoim kluczem podpisywania i go chronić wpisz informacje o swoim kluczu podpisywania.

  11. Prześlij plik APK.

  12. Kliknij Zapisz.

Utwórz swoje produkty cyfrowe

Jeśli nie masz obecnie żadnych produktów cyfrowych w Konsoli Play, wykonaj te czynności:

  1. W Konsoli Google Play kliknij Produkty w aplikacji, a następnie Produkty zarządzane. Jeśli zobaczysz ostrzeżenie, wykonaj wcześniejsze instrukcje, aby utworzyć aplikację na Androida, lub kliknij link, aby utworzyć profil sprzedawcy.
  2. Kliknij Utwórz produkt zarządzany.
  3. Wypełnij pola produktu cyfrowego. Zanotuj identyfikator produktu – dzięki temu będziesz się odwoływać do tego produktu w akcji.
  4. Kliknij Zapisz.
  5. Powtórz kroki 2–4 dla każdego produktu, który chcesz sprzedawać.

Przykład produktów, które się nie zużywają w Konsoli Google Play.

Przygotuj projekt w Actions

Po skonfigurowaniu produktów cyfrowych w Konsoli Google Play musisz włączyć transakcje cyfrowe i powiązać projekt w Actions z aplikacją Google Play.

Aby włączyć transakcje produktów cyfrowych w projekcie Actions, wykonaj te czynności:

  1. W Konsoli Actions otwórz swój projekt lub utwórz nowy.
  2. Kliknij Wdróż i wybierz Informacje z katalogu.
  3. W sekcjach Dodatkowe informacje i Transakcje zaznacz pole Tak w sekcji Czy Twoje działania używają interfejsu Digital Buy API do wykonywania transakcji na produktach cyfrowych.
  4. Kliknij Zapisz.

Tworzenie klucza interfejsu API produktów cyfrowych

Aby wysyłać żądania do interfejsu Digital products API, musisz pobrać klucz konta usługi JSON powiązany z projektem w Actions Console.

Aby pobrać klucz konta usługi, wykonaj te czynności:

  1. W prawym górnym rogu Konsoli Actions kliknij ikonę z 3 kropkami, a potem Ustawienia projektu.
  2. Znajdź identyfikator projektu akcji.
  3. Kliknij ten link, zastępując „<project_id>” identyfikatorem projektu: https://console.developers.google.com/apis/credentials?project=project_id
  4. W głównym menu nawigacyjnym otwórz Dane logowania.
  5. Na wyświetlonej stronie kliknij Utwórz dane logowania i wybierz Klucz konta usługi.
  6. Otwórz Service Account (Konto usługi) i kliknij New Service Account (Nowe konto usługi).
  7. Nadaj kontu usługi nazwę, na przykład „digitaltransactions”.
  8. Kliknij Utwórz.
  9. W polu Rola wybierz Projekt > Właściciel.
  10. Kliknij Dalej.
  11. Kliknij Utwórz klucz.
  12. Wybierz typ klucza JSON.
  13. Kliknij Utwórz klucz i pobierz klucz konta usługi JSON.

Zapisz ten klucz konta usługi w bezpiecznym miejscu. Tego klucza użyjesz podczas realizacji transakcji, aby utworzyć klienta interfejsu API zakupów cyfrowych.

Łączenie z zasobami reklamowymi Google Play

Aby mieć dostęp do produktów cyfrowych z projektu w Actions, powiąż domenę i aplikację z projektem jako połączone usługi.

Uwaga: weryfikacja Twoich usług może potrwać do tygodnia. Jeśli po tym czasie witryna lub aplikacja nie będą połączone, skontaktuj się z zespołem pomocy.

Aby połączyć domenę internetową i aplikację w Konsoli Play z projektem w Actions, wykonaj te czynności:

  1. W konsoli Actions kliknij Wdróż, a następnie Weryfikacja marki.
  2. Jeśli nie masz jeszcze połączonych żadnych usług, najpierw połącz witrynę:

    1. Kliknij przycisk usługi internetowej (</>).
    2. Wpisz adres URL domeny internetowej i kliknij Połącz.

    Google wyśle e-maila z dalszymi instrukcjami do osoby, która została zweryfikowana w przypadku danej domeny internetowej w Google Search Console. Gdy odbiorca tego e-maila wykona te czynności, witryna powinna pojawić się w sekcji Weryfikacja marki.

  3. Gdy masz już co najmniej jedną połączoną witrynę, wykonaj te czynności, aby połączyć aplikację na Androida:

    1. W konsoli Actions kliknij Wdróż, a następnie Weryfikacja marki.
    2. Kliknij Połącz aplikację.
    3. Na wyświetlonej stronie postępuj zgodnie z instrukcjami, aby zweryfikować swoją domenę w Konsoli Play. Wybierz aplikację Google Play, która zawiera Twoje produkty cyfrowe, i wpisz adres URL domeny internetowej dokładnie w takiej postaci, w jakiej jest on widoczny na stronie Weryfikacja marki.

      Ponownie Google wysyła e-maila weryfikacyjnego do zweryfikowanego właściciela domeny. Gdy zespół zatwierdzi weryfikację, Twoja aplikacja w Google Play powinna pojawić się w sekcji Weryfikacja marki.

    4. Włącz Dostęp do zakupów w Google Play.

Obraz przedstawiający witrynę i aplikacje połączone z projektem Actions.

Tworzenie procesu zakupu

Po przygotowaniu projektu Actions i asortymentu produktów cyfrowych utwórz proces zakupu produktów cyfrowych na webhooku realizacji rozmowy.

1. Konfigurowanie klienta interfejsu API zakupów cyfrowych

W webhooku realizacji rozmowy utwórz klienta JWT z kluczem JSON konta usługi i zakresem https://www.googleapis.com/auth/actions.purchases.digital.

Ten kod w środowisku Node.js tworzy klienta JWT dla interfejsu API zakupów cyfrowych:

  const serviceAccount = {'my-file.json'};
  const request = require('request');
  const {google} = require('googleapis');

  const jwtClient = new google.auth.JWT(
    serviceAccount.client_email, null, serviceAccount.private_key,
    ['https://www.googleapis.com/auth/actions.purchases.digital'],
    null
  );

2. Zbieranie informacji

Zanim użytkownik dokona zakupu, akcja zbiera informacje o jego możliwościach dokonywania zakupów oraz o tym, które produkty są dostępne w Twoim asortymencie.

2. a. Zweryfikuj wymagania dotyczące transakcji

Zanim umożliwisz użytkownikowi dokonanie zakupu, warto upewnić się, że jego konto jest skonfigurowane do wykonywania transakcji. Na tym etapie trzeba sprawdzić, czy użytkownik ma skonfigurowaną formę płatności i czy znajduje się w regionie, w którym obsługiwane są transakcje cyfrowe. Na początku procesu transakcji użyj pomocnika DIGITAL_PURCHASE_CHECK, aby za pomocą Asystenta sprawdzić konfigurację transakcji użytkownika.

Ten kod Node.js używa DIGITAL_PURCHASE_CHECK na początku rozmowy:

app.intent('Default Welcome Intent', async (conv, { SKU }) => {
  // Immediately invoke digital purchase check intent to confirm
  // purchase eligibility.
  conv.ask(new DigitalPurchaseCheck());
});

Znajdź wynik tej kontroli w argumentach rozmowy jako DIGITAL_PURCHASE_CHECK_RESULT. Na podstawie tego wyniku kontynuuj proces transakcji lub zmień kierunek transakcji i poproś o sprawdzenie konfiguracji Google Pay.

Ten kod w środowisku Node.js obsługuje wynik kontroli wymagań :

app.intent('Digital Purchase Check', async (conv) => {
  const arg = conv.arguments.get('DIGITAL_PURCHASE_CHECK_RESULT');
  if (!arg || !arg.resultType) {
    conv.close('Digital Purchase check failed. Please check logs.');
    return;
  }
  // User does not meet necessary conditions for completing a digital purchase
  if (arg.resultType === 'CANNOT_PURCHASE' || arg.resultType === 'RESULT_TYPE_UNSPECIFIED') {
    conv.close(`It looks like you aren't able to make digital purchases. Please check your Google Pay configuration and try again.`);
    return;
  }
  conv.ask('Welcome to the Digital Goods Sample. Would you like to see what I have for sale?');
});

2. b. Zbieranie dostępnych zasobów reklamowych

Za pomocą interfejsu API zakupów cyfrowych poproś o dostęp do Twojego asortymentu w Sklepie Play, a potem wbudowaj go w tablicę obiektów JSON poszczególnych produktów. Odwołujesz się do tej tablicy później, aby pokazać użytkownikowi, jakie opcje są dostępne do zakupu.

Każdy z Twoich produktów cyfrowych jest przedstawiony jako kod SKU w formacie JSON. Ten kod w środowisku Node.js określa oczekiwane formatowanie każdego kodu SKU:

body = {
  skus: [
    skuId: {
      skuType: one of "APP" or "UNSPECIFIED"
      id: string,
      packageName: string
    }
    formattedPrice: string,
    title: string,
    description: string
  ]
}

Wyślij żądanie POST do punktu końcowego https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet, gdzie {packageName} to nazwa pakietu aplikacji w Konsoli Google Play (np. com.myapp.digitalgoods), i sformatuj wynik w tablicę obiektów SKU.

Aby pobrać tylko określone produkty cyfrowe z utworzonej tablicy, podaj identyfikatory produktów cyfrowych (wyświetlane pod każdym produktem w aplikacji w Konsoli Google Play), które chcesz udostępnić w sprzedaży w body.ids.

Ten kod Node.js prosi o udostępnienie listy dostępnych produktów do interfejsu Digital purchases API i formatuje wynik jako tablicę kodów SKU:

return jwtClient.authorize((err, tokens) => {
    if (err) {
      throw new Error(`Auth error: ${err}`);
    }

    const packageName = 'com.example.projectname';

    request.post(`https://actions.googleapis.com/v3/packages/${packageName}/skus:batchGet`, {
      'auth': {
        'bearer': tokens.access_token,
      },
      'json': true,
      'body': {
        'conversationId': conversationId,
        'skuType': 'APP',
        // This request is filtered to only retrieve SKUs for the following product IDs
        'ids': ['nonconsumable.1']
      },
    }, (err, httpResponse, body) => {
      if (err) {
        throw new Error(`API request error: ${err}`);
      }
      console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
      console.log(JSON.stringify(body));
    });
  });
});

3. Tworzenie zamówienia

Aby rozpocząć proces zakupu przez użytkownika, przedstaw listę towarów cyfrowych, które można kupić. Możesz używać różnych typów odpowiedzi rozszerzonych, aby zaprezentować swoje produkty i zachęcić użytkowników do dokonania wyboru.

Ten kod Node.js odczytuje tablicę zasobów reklamowych obiektów SKU i tworzy odpowiedź typu „lista” z po jednym elementem dla każdego z nich:

skus.forEach((sku) => {
  const key = `${sku.skuId.skuType},${sku.skuId.id}`
  list.items[key] = {
    title: sku.title,
    description: `${sku.description} | ${sku.formattedPrice}`,
  };
});

4. Dokończ zakup

Aby sfinalizować zakup, użyj intencji pomocniczej COMPLETE_PURCHASE z elementem wybranym przez użytkownika.

Ten kod Node.js obsługuje wybór kodu SKU przez użytkownika z listy odpowiedzi i wysyła żądanie do intencji COMPLETE_PURCHASE z tymi informacjami:

app.intent('Send Purchase', (conv, params, option) => {
  let [skuType, id] = option.split(',');

  conv.ask(new CompletePurchase({
    skuId: {
      skuType: skuType,
      id: id,
      packageName: <PACKAGE_NAME>,
    },
  }));
});

5. Obsługa wyniku

Po dokonaniu zakupu wyzwala ono zdarzenie actions_intent_COMPLETE_PURCHASEDialogflow (lub intencję pakietu actions.intent.COMPLETE_PURCHASE Actions SDK) z argumentem COMPLETE_PURCHASE_VALUE opisującym wynik. Utwórz intencję wywoływaną przez to zdarzenie, która przekazuje wynik użytkownikowi.

Obsługuj te możliwe wyniki zakupu:

  • PURCHASE_STATUS_OK: zakup został zrealizowany. Na tym etapie transakcja jest już zakończona, więc wyjdź z niej i wróć do rozmowy.
  • PURCHASE_STATUS_ALREADY_OWNED: transakcja nie powiodła się, ponieważ użytkownik jest już właścicielem tego elementu. Aby uniknąć tego błędu, sprawdź wcześniejsze zakupy użytkownika i dostosuj wyświetlane produkty w taki sposób, aby nie mógł ponownie kupić produktów, które już posiada.
  • PURCHASE_STATUS_ITEM_UNAVAILABLE: transakcja nie powiodła się, ponieważ żądany element jest niedostępny. Aby uniknąć tego błędu, sprawdź dostępne kody SKU bliżej dnia zakupu.
  • PURCHASE_STATUS_ITEM_CHANGE_REQUESTED: transakcja nie powiodła się, ponieważ użytkownik zdecydował się kupić coś innego. Przekaż ponownie zamówienie, aby użytkownik mógł od razu podjąć inną decyzję.
  • PURCHASE_STATUS_USER_CANCELLED: transakcja nie powiodła się, ponieważ użytkownik anulował proces zakupu. Użytkownik przedwcześnie wyszedł z procesu, więc zapytaj go, czy chce ponowić transakcję, czy chce zakończyć ją razem.
  • PURCHASE_STATUS_ERROR: transakcja nie powiodła się z nieznanego powodu. Poinformuj użytkownika, że transakcja się nie powiodła, i zapytaj użytkownika, czy chce spróbować jeszcze raz.
  • PURCHASE_STATUS_UNSPECIFIED: transakcja nie powiodła się z nieznanego powodu, a jej stan jest nieznany. Aby poradzić sobie z tym stanem błędu, poinformuj użytkownika, że transakcja się nie powiodła, i zapytaj, czy chce spróbować ponownie.

Ten kod Node.js odczytuje argument COMPLETE_PURCHASE_VALUE i obsługuje każdy wynik:

app.intent('Purchase Result', (conv) => {
  const arg = conv.arguments.get('COMPLETE_PURCHASE_VALUE');
  console.log('User Decision: ' + JSON.stringify(arg));
  if (!arg || !arg.purchaseStatus) {
    conv.close('Purchase failed. Please check logs.');
    return;
  }
  if (arg.purchaseStatus === 'PURCHASE_STATUS_OK') {
    conv.close(`Purchase completed! You're all set!`);
  } else if (arg.purchaseStatus === 'PURCHASE_STATUS_ALREADY_OWNED') {
    conv.close('Purchase failed. You already own this item.');
  } else if (arg.purchaseStatus === 'PURCHASE_STATUS_ITEM_UNAVAILABLE') {
    conv.close('Purchase failed. Item is not available.');
  } else if (arg.purchaseStatus === 'PURCHASE_STATUS_ITEM_CHANGE_REQUESTED') {
    // Reprompt with your item selection dialog
  }  else {
    conv.close('Purchase Failed:' + arg.purchaseStatus);
  }
});

Odzwierciedlać zakupy użytkownika

Gdy użytkownik wysyła zapytanie do akcji, obiekt user żądania JSON zawiera listę jego zakupów. Sprawdź te informacje i zmień odpowiedź w zależności od tego, za jakie treści użytkownik zapłacił.

Poniższy przykładowy kod przedstawia obiekt user żądania, który zawiera packageEntitlements wcześniejszych zakupów w aplikacji dotyczących pakietu com.digitalgoods.application:

  "user": {
    "userId": "xxxx",
    "locale": "en-US",
    "lastSeen": "2018-02-09T01:49:23Z",
    "packageEntitlements": [
      {
        "packageName": "com.digitalgoods.application",
        "entitlements": [
          {
            "sku": "non-consumable.1",
            "skuType": "APP"
          }
          {
            "sku": "consumable.2",
            "skuType": "APP"
          }
        ]
      },
      {
        "packageName": "com.digitalgoods.application",
        "entitlements": [
          {
            "sku": "annual.subscription",
            "skuType": "SUBSCRIPTION",
            "inAppDetails": {
              "inAppPurchaseData": {
                "autoRenewing": true,
                "purchaseState": 0,
                "productId": "annual.subscription",
                "purchaseToken": "12345",
                "developerPayload": "HSUSER_IW82",
                "packageName": "com.digitalgoods.application",
                "orderId": "GPA.233.2.32.3300783",
                "purchaseTime": 1517385876421
              },
              "inAppDataSignature": "V+Q=="
            }
          }
        ]
      }
    ]
  },
  "conversation": {
    "conversationId": "1518141160297",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.MAIN",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "Talk to My Test App"
        }
      ]
    }
  ],
  ...
}