Integration principles
Your connection to Voyado must never be critical to the purchase process in checkout, nor to any other business critical contact transaction. A contact should always be able to perform their entire purchase in the POS and e-com, regardless of problems like the client's broadband being down, or firewalls not working, or the Engage API not responding.
Important
Your systems should continue to operate even if communication to Voyado is down.
A customer should therefore prepare for performance issues, or even the case where communication to Voyado, for whatever reason, is not available. There are several levels of preparation a customer can consider, according to their needs, budget, and ambitions. This can be seen as a kind of insurance. The more a customer invests, in terms of time, planning and resources, the fewer problems and data loss they risk in case of failure.
Cases 2, 3 and 4 below require purchases to be imported to Engage either via XML or API with buffer or temp-DB for potential downtime.
With an intelligent buffer for purchases WITH contact data, it is possible for the integration part to decide whether the contact registered should be pushed as a new contact or only tag the transaction to an existing contact when the connection is back up.
This is the case where no fail-safe for contact-handling exists. However, the purchase process must always proceed. Here are a few suggestions for when a connection fail happens.
Notifying customers that the loyalty program is down using messages/alerts:
”There were problems handling your member/customer data. You can proceed with your purchase but will not be able to use your individual member/customer offers. This purchase will also not generate reward points due to this issue. We regret the inconvenience. Contact Customer service for more info.”
Apply loyalty offers to all
As an apologetic gesture you could open up general customer/member offers to all.
Note
No new contacts can be registered during this downtime.
In order to be able to tag transactions with a contact ID even though there is no communication with Engage, a secondary integration key should be implemented.
Normally we recommend that transactions are tagged with a contact ID: not personal information, such as a mobile phone number, but rather an Engage contact ID or a generic member number. Then the POS or e-com must always take that public identifier (such as a mobile phone number or a social security number in Sweden) and check using the API which integration key should be used.
Our recommendation is to use one or more of the public identifiers, such as a mobile phone number or email address as a secondary integration key, that is, to tag the mobilePhone to the transaction instead of the primary integration key. This is then matched as mobilePhone data in Engage.
Example using primary integration key, in this case “memberNumber”:
{
"contact": {
"matchKey": "28972987289",
"matchKeyType": "memberNumber",
"contactType": "member"
},
"uniqueReceiptId": "2018468464468",
"receiptNumber": "468464468"
.......Example using secondary integration key, in this case “mobilePhone”:
{
"contact": {
"matchKey": "46707234567",
"matchKeyType": "mobilePhone",
"contactType": "member"
},
"uniqueReceiptId": "2018468464468",
"receiptNumber": "468464468"
.......Note
Reward points will be accounted for and reward vouchers can be used when coded into the transaction.
Note
It is critical, as a GDPR compliance, that the integrator deletes all local logging and temporary storing of this integration data when it contains personal information. Engage flushes integration logs and files after a certain time and the integrator should too.
Note
No new contacts can be registered during this downtime.
In this case, a reasonably fresh copy of Engage's contact database resides locally in the e-com platform and/or POS. This is obtained via a primary data download from Engage and incremental delta import via Engage's contact export XML. This export can be as complex as it needs to be, either:
A small database that just allows the integration key to be tagged to a transaction
A database containing fully-fledged contact objects
Note
No new contacts can be registered during this downtime.
Use Engages bulk read changes API to fetch all contact changes from Engage in a single API call.
In this case, a reasonably fresh copy of Engage's contact-DB resides locally in the e-com platform and/or POS. This is obtained via a primary data download from Engage and incremental delta import via Engage's contact export XML.
In addition to this it is possible to create and change contacts locally and sync them incrementally to Engage. The data is obtained via delta export from Engage via XML import.
Note
In this case the integration key can't be the Engage internal contact ID. Instead it will be a number sequence created by the integrator's environment when it creates new contacts or some secondary integration key used specifically for this situation.
To write all local contact changes to Engage in a single API call, use the bulk write contacts API endpoint.