Logo
Blog

👨🏻‍🏫 Query GraphQL do automatycznego wysyłania subskrybentów newslettera z InstaWP do Mailchimp

Leonardo Losoviz
Autor: Leonardo Losoviz ·

(Przeczytaj post na blogu 🚀 Automatyczne wysyłanie subskrybentów newslettera z InstaWP do Mailchimp, aby zobaczyć kontekst tej queries.)

Ta query GraphQL przechwytuje adres e-mail odwiedzających, którzy zaznaczyli pole wyboru "Subscribe to mailing list" w InstaWP (podczas tworzenia nowej witryny sandbox), i zapisuje ten adres e-mail na liście Mailchimp:

query HasSubscribedToNewsletter {
  hasSubscriberOptIn: _httpRequestHasParam(name: "marketing_optin")
  subscriberOptIn: _httpRequestStringParam(name: "marketing_optin")
  isNotSubscriberOptInNAValue: _notEquals(value1: $__subscriberOptIn, value2: "NA")
  subscribedToNewsletter: _and(values: [$__hasSubscriberOptIn, $__isNotSubscriberOptInNAValue])
    @export(as: "subscribedToNewsletter")
}
 
query MaybeCreateContactOnMailchimp
   @depends(on: "HasSubscribedToNewsletter")
   @include(if: $subscribedToNewsletter)
{
  subscriberEmail: _httpRequestStringParam(name: "email")
  
  mailchimpUsername: _env(name: "MAILCHIMP_API_CREDENTIALS_USERNAME")
    @remove
  mailchimpPassword: _env(name: "MAILCHIMP_API_CREDENTIALS_PASSWORD")
    @remove
  
  mailchimpListMembersJSONObject: _sendJSONObjectItemHTTPRequest(input: {
    url: "https://us7.api.mailchimp.com/3.0/lists/{listCode}/members",
    method: POST,
    options: {
      auth: {
        username: $__mailchimpUsername,
        password: $__mailchimpPassword
      },
      json: {
        email_address: $__subscriberEmail,
        status: "subscribed"
      }
    }
  })
}

Alternatywnie możesz też rejestrować subskrybentów w swoim wtyczce newslettera dla WordPress (np. Noptin lub innej).

Zobaczmy, jak ta query GraphQL działa.

Podział query GraphQL na niezależne jednostki

Dokument GraphQL może zawierać wiele operacji (queries i mutations), ale tylko jedna z nich zostanie wykonana. Wskazujemy którą za pomocą parametru ?operationName=... na endpoincie GraphQL; w przeciwnym razie zostanie wykonana ostatnia operacja.

Zauważ, że w powyższym dokumencie znajdują się 2 operacje query:

  1. HasSubscribedToNewsletter
  2. MaybeCreateContactOnMailchimp

URL webhooka zawiera ?operationName=MaybeCreateContactOnMailchimp, więc to jest operacja, która zostanie wykonana.

Dzięki rozszerzeniu Multiple Query Execution, MaybeCreateContactOnMailchimp najpierw wykona HasSubscribedToNewsletter, jak wskazuje dyrektywa @depends:

query MaybeCreateContactOnMailchimp
   @depends(on: "HasSubscribedToNewsletter")
   # ...
{
  #
}

Ponadto MaybeCreateContactOnMailchimp zostanie wykonana warunkowo, tylko jeśli wartość zmiennej $subscribedToNewsletter wynosi true:

query MaybeCreateContactOnMailchimp
   @depends(on: "HasSubscribedToNewsletter")
   @include(if: $subscribedToNewsletter)
{
  #
}

$subscribedToNewsletter jest zmienną dynamiczną, eksportowaną wewnątrz operacji HasSubscribedToNewsletter:

query HasSubscribedToNewsletter {
  # ...
  subscribedToNewsletter: _and(values: [$__hasSubscriberOptIn, $__isNotSubscriberOptInNAValue])
    @export(as: "subscribedToNewsletter")
}

Zatem operacja MaybeCreateContactOnMailchimp zostanie wykonana tylko wtedy, gdy użytkownik zaznaczył pole wyboru "Subscribe to mailing list".

Sprawdzanie, czy użytkownik zaznaczył pole wyboru

Dokumentacja webhooka InstaWP wskazuje, że dane payloadu zawierają następujące pola (między innymi):

  • marketing_optin: Wskazuje, czy użytkownik zaznaczył pole wyboru
  • email: Adres e-mail odwiedzającego

Dokumentacja wyjaśnia jedynie, że pole marketing_optin ma wartość NA, gdy pole wyboru nie jest zaznaczone, więc będziemy musieli z tym pracować.

Aby dowiedzieć się, czy użytkownik zaznaczył pole wyboru, logika jest następująca:

  • Sprawdź, czy pole marketing_optin jest obecne, oraz
  • Sprawdź, czy jego wartość nie wynosi NA

Jest to obliczane w operacji HasSubscribedToNewsletter. Oto ona z komentarzami wyjaśniającymi, co robi każda linia queries:

query HasSubscribedToNewsletter {
 
  # Check if field `marketing_optin` is present
  hasSubscriberOptIn: _httpRequestHasParam(name: "marketing_optin")
 
  # Get the value of field `marketing_optin`
  subscriberOptIn: _httpRequestStringParam(name: "marketing_optin")
 
  # Check if the value of the field is not "NA"
  isNotSubscriberOptInNAValue: _notEquals(value1: $__subscriberOptIn, value2: "NA")
 
  # Perform an AND operation: field present && value != "NA"
  subscribedToNewsletter: _and(values: [$__hasSubscriberOptIn, $__isNotSubscriberOptInNAValue])
    
    # Export the result under dynamic variable $subscribedToNewsletter
    @export(as: "subscribedToNewsletter")
}

W tej queries jest kilka interesujących rzeczy.

Pola globalne

Czy zauważyłeś pola zaczynające się od _? A mianowicie:

  • _httpRequestHasParam
  • _httpRequestStringParam
  • _notEquals
  • _and

Są to pola globalne, czyli pola dostępne pod wszystkimi typami w schemacie GraphQL. Pola globalne oferują funkcjonalność zamiast danych i zgodnie z konwencją zaczynają się od _.

Field to Input

Czy zauważyłeś te zmienne zaczynające się od $__? A mianowicie:

  • $__subscriberOptIn
  • $__hasSubscriberOptIn
  • $__isNotSubscriberOptInNAValue

Są to zmienne dynamiczne zawierające wartość pola zdefiniowanego przed nimi w tej samej operacji. Na przykład zmienna $__subscriberOptIn zawiera wartość pola subscriberOptIn zadeklarowanego powyżej.

Jest to funkcja dostarczana przez rozszerzenie Field to Input, które umożliwia użycie danych wyjściowych pola jako danych wejściowych do innego pola. W ten sposób możemy tworzyć funkcjonalność w ramach query GraphQL.

W queries pole isNotSubscriberOptInNAValue sprawdza, czy wartość wcześniej odpytanego pola subscriberOptIn nie jest równa "NA", a subscribedToNewsletter oblicza operację AND obejmującą wartości pól hasSubscriberOptIn i isNotSubscriberOptInNAValue.

Łączenie z Mailchimp

Operacja MaybeCreateContactOnMailchimp zawiera logikę do wyodrębnienia danych payloadu i wywołania API Mailchimp w celu zapisania adresu e-mail na liście newslettera.

Oto operacja z komentarzami wyjaśniającymi, co robi każda linia:

query MaybeCreateContactOnMailchimp
   @depends(on: "HasSubscribedToNewsletter")
   @include(if: $subscribedToNewsletter)
{
  # Extract form field `email` from the body of the request
  subscriberEmail: _httpRequestStringParam(name: "email")
  
  # Obtain Mailchimp credentials, defined in wp-config.php
  mailchimpUsername: _env(name: "MAILCHIMP_API_CREDENTIALS_USERNAME")
    # Do not print the credentials in the response
    @remove
  mailchimpPassword: _env(name: "MAILCHIMP_API_CREDENTIALS_PASSWORD")
    @remove
  
  # Connect to Mailchimp to add a new member to the list
  mailchimpListMembersJSONObject: _sendJSONObjectItemHTTPRequest(input: {
    url: "https://us7.api.mailchimp.com/3.0/lists/{listCode}/members",
    method: POST,
    options: {
      # Provide credentials to connect to the API
      auth: {
        username: $__mailchimpUsername,
        password: $__mailchimpPassword
      },
      # Provide form data
      json: {
        email_address: $__subscriberEmail,
        status: "subscribed"
      }
    }
  })
}

Przyjrzyjmy się funkcjom używanym w tej queries.

Zmienne środowiskowe

Musimy podać nasze dane uwierzytelniające podczas łączenia z API Mailchimp. Nie chcemy jednak wprowadzać ich bezpośrednio w query GraphQL, ponieważ mogą gdzieś wyciec (np. mogą zostać wydrukowane w jakimś logu).

Dlatego używamy pola globalnego _env (dostarczanego przez rozszerzenie PHP Constants and Environment via Schema) do odczytu zmiennej środowiskowej lub stałej PHP, wraz z dyrektywą @remove (dostarczaną przez rozszerzenie Field Response Removal), aby uniknąć drukowania danych uwierzytelniających w odpowiedzi.

Teraz możemy zadeklarować nasze dane uwierzytelniające w wp-config.php:

define( 'MAILCHIMP_API_CREDENTIALS_USERNAME', '{ username }' );
define( 'MAILCHIMP_API_CREDENTIALS_PASSWORD', '{ password }' );

Wysyłanie żądania HTTP do Mailchimp

Ostatnim elementem logiki jest pole _sendJSONObjectItemHTTPRequest, które wysyła żądanie HTTP do jakiegoś serwisu.

Ponieważ chcemy połączyć się z API Mailchimp, pole mailchimpListMembersJSONObject dostarcza dane wymagane przez endpoint REST API Mailchimp, jak wskazano w dokumentacji dotyczącej zapisywania członka na listę Mailchimp:

  • Wyślij żądanie POST
  • Endpoint to https://{subdomain}.api.mailchimp.com/3.0/lists/{listCode}/members
  • Treść musi zawierać pola email_address i status

Tworzenie webhooka do interakcji z dowolnym API

Query GraphQL w tym poście przekazuje dane z InstaWP do Mailchimp.

Możesz zastosować tę samą ideę do dowolnej kombinacji, której potrzebujesz, wyodrębniając dane z jakiegoś serwisu źródłowego (jakiegokolwiek), adaptując je i wysyłając do jakiegoś serwisu docelowego (jakiegokolwiek).

Miłej zabawy!

Powrót do wszystkich wpisów

Zapisz się do naszego newslettera

Bądź na bieżąco ze wszystkimi aktualizacjami Gato GraphQL.