Logo
Blog

👨🏻‍🏫 Query GraphQL per inviare automaticamente gli iscritti alla newsletter da InstaWP a Mailchimp

Leonardo Losoviz
Di Leonardo Losoviz ·

(Leggi l'articolo del blog 🚀 Inviare automaticamente gli iscritti alla newsletter da InstaWP a Mailchimp per vedere il contesto di questa query.)

Questa query GraphQL cattura l'e-mail dei visitatori che hanno spuntato la casella « Subscribe to mailing list » in InstaWP (durante la creazione di un nuovo sito sandbox), e iscrive questa e-mail a una lista 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"
      }
    }
  })
}

In alternativa, puoi anche registrare gli iscritti nel tuo plugin di newsletter per WordPress (es: Noptin o un altro).

Vediamo come questa query GraphQL fa la sua magia.

Suddividere la query GraphQL in unità indipendenti

Un documento GraphQL può contenere più operazioni (query e mutation), ma solo una di esse verrà eseguita. Indichiamo quale tramite il parametro ?operationName=... sull'endpoint GraphQL; altrimenti, verrà eseguita l'ultima operazione.

Nota che ci sono 2 operazioni query nel documento qui sopra:

  1. HasSubscribedToNewsletter
  2. MaybeCreateContactOnMailchimp

L'URL del webhook contiene ?operationName=MaybeCreateContactOnMailchimp, quindi è questa l'operazione che verrà eseguita.

Grazie all'estensione Multiple Query Execution, MaybeCreateContactOnMailchimp eseguirà prima HasSubscribedToNewsletter, come indicato dalla direttiva @depends:

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

Inoltre, MaybeCreateContactOnMailchimp verrà eseguita in modo condizionale, solo se il valore della variabile $subscribedToNewsletter è true:

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

$subscribedToNewsletter è una variabile dinamica, esportata all'interno dell'operazione HasSubscribedToNewsletter:

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

Pertanto, l'operazione MaybeCreateContactOnMailchimp verrà eseguita solo quando l'utente ha spuntato la casella « Subscribe to mailing list ».

Calcolare se l'utente ha spuntato la casella

La documentazione del webhook di InstaWP indica che i dati del payload contengono i seguenti campi (tra gli altri):

  • marketing_optin: Indica se l'utente ha spuntato la casella
  • email: E-mail del visitatore

La documentazione spiega solo che il campo marketing_optin ha valore NA quando la casella non è spuntata, quindi dovremo lavorare con questo.

Per scoprire se l'utente ha spuntato la casella, la logica è:

  • Verificare se il campo marketing_optin è presente, e
  • Verificare che il suo valore non sia NA

Questo viene calcolato nell'operazione HasSubscribedToNewsletter. Eccola con i commenti, che spiegano cosa fa ogni riga della query:

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

Ci sono diverse cose interessanti in questa query.

Campi globali

Hai notato i campi che iniziano con _? Ovvero:

  • _httpRequestHasParam
  • _httpRequestStringParam
  • _notEquals
  • _and

Questi sono campi globali, che sono campi disponibili sotto tutti i tipi nello schema GraphQL. I campi globali offrono funzionalità invece di dati, e per convenzione iniziano con _.

Field to Input

Hai notato quelle variabili che iniziano con $__? Ovvero:

  • $__subscriberOptIn
  • $__hasSubscriberOptIn
  • $__isNotSubscriberOptInNAValue

Queste sono variabili dinamiche che contengono il valore di un campo definito prima di esse all'interno della stessa operazione. Per esempio, la variabile $__subscriberOptIn contiene il valore del campo subscriberOptIn dichiarato sopra di essa.

Questa è una funzionalità fornita dall'estensione Field to Input, che permette di usare l'output di un campo come input in un altro campo. È così che possiamo creare funzionalità all'interno della query GraphQL.

Nella query, il campo isNotSubscriberOptInNAValue verifica che il valore del campo precedentemente interrogato subscriberOptIn non sia uguale a "NA", e subscribedToNewsletter calcola un'operazione AND che coinvolge i valori dei campi hasSubscriberOptIn e isNotSubscriberOptInNAValue.

Connettersi a Mailchimp

L'operazione MaybeCreateContactOnMailchimp contiene la logica per estrarre i dati del payload e chiamare l'API di Mailchimp per iscrivere l'e-mail alla lista della newsletter.

Ecco l'operazione con i commenti, che spiegano cosa fa ogni riga:

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

Esploriamo le funzionalità utilizzate in questa query.

Variabili d'ambiente

Dobbiamo fornire le nostre credenziali quando ci connettiamo all'API di Mailchimp. Tuttavia, non vogliamo inserirle direttamente nella query GraphQL, poiché potrebbero trapelare da qualche parte (es: potrebbero essere stampate in qualche log).

Ecco perché usiamo il campo globale _env (fornito dall'estensione PHP Constants and Environment via Schema) per leggere una variabile d'ambiente o una costante PHP, insieme alla direttiva @remove (fornita dall'estensione Field Response Removal) per evitare di stampare le credenziali nella risposta.

Ora possiamo dichiarare le nostre credenziali in wp-config.php:

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

Inviare la richiesta HTTP a Mailchimp

L'ultimo elemento della logica è il campo _sendJSONObjectItemHTTPRequest, che invia una richiesta HTTP a un servizio.

Poiché vogliamo connetterci all'API di Mailchimp, il campo mailchimpListMembersJSONObject fornisce i dati richiesti dall'endpoint della REST API di Mailchimp, come indicato nella documentazione per iscrivere un membro a una lista Mailchimp:

  • Inviare una richiesta POST
  • L'endpoint è https://{subdomain}.api.mailchimp.com/3.0/lists/{listCode}/members
  • Il corpo deve includere i campi email_address e status

Creare un webhook per interagire con qualsiasi API

La query GraphQL di questo articolo inoltra i dati da InstaWP a Mailchimp.

Puoi applicare la stessa idea per qualsiasi combinazione di cui hai bisogno, estraendo i dati da un servizio di origine (qualunque esso sia), adattandoli e inviandoli a un servizio di destinazione (qualunque esso sia).

Divertiti!

Torna a tutti gli articoli

Iscriviti alla nostra newsletter

Resta aggiornato su tutte le novità di Gato GraphQL.