👨🏻‍🏫 Requête GraphQL pour envoyer automatiquement les abonnés à la newsletter d'InstaWP à Mailchimp

(Lisez l'article de blog 🚀 Envoi automatique des abonnés à la newsletter d'InstaWP à Mailchimp pour voir le contexte de cette requête.)

Cette requête GraphQL capture l'e-mail des visiteurs qui ont coché la case « Subscribe to mailing list » dans InstaWP (lors de la création d'un nouveau site sandbox), et abonne cet e-mail à une liste 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"
      }
    }
  })
}Copy

Vous pouvez également enregistrer les abonnés dans votre plugin de newsletter WordPress (ex : Noptin ou un autre).

Voyons comment cette requête GraphQL fait sa magie.

​

Diviser la requête GraphQL en unités indépendantes

Un document GraphQL peut contenir plusieurs opérations (requêtes et mutations), mais une seule d'entre elles sera exécutée. Nous indiquons laquelle via le paramètre ?operationName=... sur l'endpoint GraphQL ; sinon, la dernière opération sera exécutée.

Remarquez qu'il y a 2 opérations query dans le document ci-dessus :

1. HasSubscribedToNewsletter
2. MaybeCreateContactOnMailchimp

L'URL du webhook contient ?operationName=MaybeCreateContactOnMailchimp, donc c'est l'opération qui sera exécutée.

Grâce à l'extension Exécution de multiples requêtes, MaybeCreateContactOnMailchimp exécutera d'abord HasSubscribedToNewsletter, comme indiqué via la directive @depends :

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

De plus, MaybeCreateContactOnMailchimp sera exécutée conditionnellement, seulement si la valeur de la variable $subscribedToNewsletter est true :

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

$subscribedToNewsletter est une variable dynamique, exportée dans l'opération HasSubscribedToNewsletter :

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

Ainsi, l'opération MaybeCreateContactOnMailchimp ne sera exécutée que lorsque l'utilisateur a coché la case « Subscribe to mailing list ».

​

Calculer si l'utilisateur a coché la case

La documentation du webhook d'InstaWP indique que les données du payload contiennent les champs suivants (entre autres) :

• marketing_optin : Indique si l'utilisateur a coché la case
• email : E-mail du visiteur

La documentation explique seulement que le champ marketing_optin a la valeur NA lorsque la case n'est pas cochée, donc nous devrons travailler avec cela.

Pour savoir si l'utilisateur a coché la case, la logique est :

• Vérifier si le champ marketing_optin est présent, et
• Vérifier que sa valeur n'est pas NA

Cela est calculé dans l'opération HasSubscribedToNewsletter. La voici avec des commentaires, expliquant ce que fait chaque ligne de la requête :

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

Il y a plusieurs choses intéressantes dans cette requête.

​

Champs globaux

Avez-vous remarqué les champs commençant par _ ? À savoir :

• _httpRequestHasParam
• _httpRequestStringParam
• _notEquals
• _and

Ce sont des champs globaux, qui sont des champs disponibles sous tous les types dans le schéma GraphQL. Les champs globaux offrent des fonctionnalités plutôt que des données, et par convention ils commencent par _.

​

Field to Input

Avez-vous remarqué ces variables commençant par $__ ? À savoir :

• $__subscriberOptIn
• $__hasSubscriberOptIn
• $__isNotSubscriberOptInNAValue

Ce sont des variables dynamiques qui contiennent la valeur d'un champ défini avant elles dans la même opération. Par exemple, la variable $__subscriberOptIn contient la valeur du champ subscriberOptIn déclaré au-dessus d'elle.

C'est une fonctionnalité fournie par l'extension Field to Input, qui permet d'utiliser la sortie d'un champ comme entrée dans un autre champ. C'est ainsi que nous pouvons créer des fonctionnalités dans la requête GraphQL.

Dans la requête, le champ isNotSubscriberOptInNAValue vérifie que la valeur du champ précédemment interrogé subscriberOptIn n'est pas égale à "NA", et subscribedToNewsletter calcule une opération AND impliquant les valeurs des champs hasSubscriberOptIn et isNotSubscriberOptInNAValue.

​

Se connecter à Mailchimp

L'opération MaybeCreateContactOnMailchimp contient la logique pour extraire les données du payload, et appeler l'API Mailchimp pour inscrire l'e-mail à la liste de newsletter.

Voici l'opération avec des commentaires, expliquant ce que fait chaque ligne :

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

Explorons les fonctionnalités utilisées dans cette requête.

​

Variables d'environnement

Nous devons fournir nos identifiants lors de la connexion à l'API Mailchimp. Cependant, nous ne voulons pas les saisir directement dans la requête GraphQL, car ils pourraient fuiter quelque part (ex : ils pourraient être imprimés dans un log).

C'est pourquoi nous utilisons le champ global _env (fourni par l'extension Constantes PHP et Variables d'Environnement via le Schéma) pour lire une variable d'environnement ou une constante PHP, ainsi que la directive @remove (fournie par l'extension Suppression de la Réponse d'un Champ) pour éviter d'imprimer les identifiants dans la réponse.

Maintenant, nous pouvons déclarer nos identifiants dans wp-config.php :

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

​

Envoi de la requête HTTP à Mailchimp

Le dernier élément de la logique est le champ _sendJSONObjectItemHTTPRequest, qui envoie une requête HTTP à un service.

Comme nous voulons nous connecter à l'API Mailchimp, le champ mailchimpListMembersJSONObject fournit les données requises par l'endpoint de la REST API de Mailchimp, comme indiqué dans la documentation pour souscrire un membre à une liste Mailchimp :

• Envoyer une requête POST
• L'endpoint est https://{subdomain}.api.mailchimp.com/3.0/lists/{listCode}/members
• Le corps doit inclure les champs email_address et status

​

Créer un webhook pour interagir avec n'importe quelle API

La requête GraphQL de cet article transfère les données d'InstaWP à Mailchimp.

Vous pouvez appliquer la même idée pour n'importe quelle combinaison dont vous avez besoin, en extrayant les données d'un service source (quel qu'il soit), en les adaptant, et en les envoyant à un service de destination (quel qu'il soit).

Amusez-vous bien !