Guida mailchimp per sviluppatori: api v3 utilizzando php

Scopriamo come lavorare al meglio con le api v3 di Mailchimp utilizzando PHP

Avete mai avuto l’esigenza di dovervi interfacciare con la vostra lista di Mailchimp, o semplicemente avete bisogno di poter inserire nuovi utenti utilizzando flussi di acquisizione personalizzati? Questo articolo fa al caso vostro.

Cosa andremo a realizzare

Engine per il recupero e interfacciamento con una lista collegata al vostro account Mailchimp. Potremo leggere gli iscritti di una lista e  inserire nuovi contatti all’interno della stessa. Potremo altresì effettuare un’azione di remarketing quando l’utente – gia iscritto precedentemente – si ricollega al sito.

Operazioni preliminari

Per prima cosa dobbiamo recuperare essenzialmente 3 elementi:

  1. endpoint del server collegato al nostro account
  2. api key
  3. id della lista

Il primo punto è relativamente semplice, una volta loggati guardate la barra degli indirizzi e dovrebbe apparire come segue:

https://<server>.admin.mailchimp.com

Ovviamente al posto di server dovrete sostituire quello che vedete a schermo nel vostro caso specifico.

Per recuperare l’api key agite come segue:

(In alto a destra) Account –> extras –> api keys –> “Create a key”

Per recuperare l’id della lista invece (terzo punto):

Lists –> Setting –> “List name and campaign defaults” –> List id si trova a fianco al nome della lista

NOTA BENE: Contrariamente a quanto pensate l’id  NON è quello presente nell’url di modifica

Creiamo il nostro engine php

Ora che abbiamo i dati essenziali per accedere, andiamo ad analizzare la creazione dell’engine in php. Per questo tutorial useremo la versione V3 delle api di Mailchimp.

Creiamo per prima cosa un file mailchimp-config.php che conterrà i valori del nostro account.

File: mailchimp-config.php

<?php
//Developed by Riccardo Mel
$apiKey = "TUA KEY";
$server = "https://TUOSERVER.api.mailchimp.com/3.0/";
?>

A questo punto generiamo un file engine.php e iniziamo a strutturare l’acquisizione delle variabili.

Codice completo engine.php

Per prima cosa andiamo a definire le variabili in ingresso che saranno: email, nome, debug, action, listid

Nello specifico:

  • debug –> attiva o disattiva il print dei messaggi –> default 0
  • action–> specifica se la chiamata è per inserire (subscribe) o leggere la lista (lists). In produzione ovviamente va messo fisso su subscribe
  • listId –> Specifica id lista. In produzione ovviamente va messo fisso.
  • fname  –> Nome per l’inserimento in lista
  • email  –> Email per l’inserimento in lista

Ho aggiunto anche un controllo per il check dell mail nel caso l’action sia di inserimento.

File engine.php | #Codice parziale 1

Nella seconda parte di codice invece parte il curl che invia dapprima le informazioni di autenticazione con CURLOPT_HTTPEADER dopodichè tramite un semplice switch case php identifico il valore di action e aggiungo (se l’action è subscribe) o visualizzo l’elenco dei contatti su mailchimp (se l’action è lists).

Da notare una differenza sostanziale derivante da Mailchimp: Per aggiungere dovete passare in CURL i valori con POST (CURLOPT_POST) se dovete leggere la lista l’endpoint è il medesimo ma va fatta una  come chiamata GET.

File engine.php | #Codice parziale 2

Codice frontend

Ora che abbiamo creato il nostro motore php dobbiamo rendere il tutto usabile (Di fatto l’engine php attualmente è utilizzabile solo passando i parametri come GET tramite la barra degli indirizzi). Per farlo realizzeremo nella fattispecie:

  1. Overlay al caricamento della pagina 
  2. Cookie per il controllo dell’overlay in modo che appaia solo dopo un tot di ore/tempo configurabile
  3. Cookie di remarketing per effettuare un’azione al ritorno del visitatore, anche una volta che si è iscritto in modo da fidelizzarlo
  4. Cookie informativo con nome ed email usata dall’utente per registrarsi alla nostra lista mailchimp, in modo tale da poter personalizzare l’esperienza utente.
  5. Possibilità di localizzare i messaggi (grossa mancanza di mailchimp ).

Per fare gli overlay useremo questo mio tool ma potete usarne qualsiasi altro vogliate. Per i cookie invece ho usato queste librerie che trovo davvero comode.

Codice completo file index.php

Di base appare il primo overlay contenente il form di acquisizione per mailchimp (ovviamente potete commentare o nascondere i campi che non servono per l’utente finale, come il debug etc). Nel caso della produzione vi consiglio di mettere la lista ovviamente statica facendola puntare alla vostra.

Una volta che l’utente compila e invia l’iscrizione con ajax (senza reload) nascondo il primo overlay automaticamente e faccio apparire quello di ringraziamento che conterrà anche eventualmente un messaggio localizzabile (nel file engine.php) per l’utente finale.

Contemporaneamente salvo nel cookie “remarketing_cookie_info” le informazioni essenziali di chi ho davanti allo schermo (nome, email) in modo tale da personalizzare l’esperienza sul sito.

Ultimo – ma estremamente utile – il cookie remarketing: si attiva al successivo reload/rientro dell’utente nel sito e permette di specificare un messaggio/ulteriore azione da compiere. Ad esempio suggerire un like sulla propria facebook page.

NOTA: consiglio di modificare i valori di expires dei cookie in base alle vostre specifiche esigenze.

Note e conclusioni

DOCUMENTAZIONE UFFICIALE

Questo articolo ti è stato utile? Condividilo sui tuoi social preferiti oppure seguici su facebook!

Image Credits “Newsletter” disponibile su Shutterstock

Lascia la tua opinione

×