Integrations with Lipscore consists of two parts: 

1. Backend integration – the transfer of order/purchase/transaction data to Lipscore for the purpose of scheduling review invitations (emails or sms-messages). This is most commonly done with custom integration modules, and how to create such a module is described in detail in this document. 

2. Frontend integration – displaying Lipscore ratings and reviews on a website, native mobile apps or other types of screens is commonly handled using widgets. Widget installation is described in some detail in this document.  

Whichever platform the module is being developed for, there are some common elements that need to be in place for the app to serve its purpose and work seamlessly.  

Required functionalities

The module needs to include the following functionality: 

1. Automatic installation / uninstallation via the platforms “app store” (module download via Github / manual installation is also an option) 

2. A settings page to configure the module 

3. Automatic transfer of order/purchase data to Lipscore via the API 

4. Automatic installation of the initializer script on all website pages 

5. (Shortcodes for widget installation is not required but strongly recommended) 

Please note:  
The module and it’s functionality needs to be tested and approved by Lipscore employees before it can be released.  

Requirements for a fully functional module

Backend integration  

The primary function of the module you are about to create is to schedule review invitations. One invitation corresponds with one purchase/order and can include multiple products. You only need to trigger one single API call per order (multiple calls with the same data will give errors) 

API documentation: https://members.lipscore.com/apidoc/v2/purchases/create.html 

When to trigger the data transfer 

It is critical that the module triggers the invitation method in the API when the order status reaches status completed / shipped / etc. Some products or services take a long time between ordering and delivering and it is vital that the invitation is created in the Lipscore system as close to when the customer receives the products / services as possible. 

Selecting the right Order status that triggers the data transfer to Lipscore needs to be a setting inside the module (it may vary between different implementations). See Settings in the module section for more information.  

Data to be sent to Lipscore 

1. All available fields, both Required and Optional, needs to be included in the API request to Lipscore. The modules need to include as many optional fields as possible because there is a lot of functionality inside the Lipscore system tied to these fields. Please note that Product URL needs to be an actual, fully qualified URL to the product detail page (not just e.g., homepage URL) 

2. Data marked as Recommended in the API documentation are particularly important to include for some Lipscore functionalities to work, and we definitely need it to be transferred to us:  

• GTIN numbers (for Google Shopping ads and Google organic search to display customer feedback). Unlike Product ID, GTINs need to be sent per variant. 
• Product category data (for Product Attributes functionality, blocking categories from reviewing, forcing Service reviews on certain categories, etc) 
• Brand (for analyzing brands performance) 

Settings in the module  

It should be possible for the Customer to activate the backend integration on their own.  

Here are the required settings that should be available for the customer in the module. 

1. Select store view (if applicable) 
   If a customer has separate websites configured in the same installation, e.g., example.co.uk and example.com, they should be able to select which website they are doing the configuration for, and have different settings per website. Not all platforms have support for this type of functionality.  

2. Adding API key and Secret API key  
   Fields where Customers will paste the API keys that can be found in the Lipscore account. API keys are how our system matches a Lipscore account with a website. The public API key should automatically be inserted in the Initializer Script in the websites <head> section.  
   See: Initializer script – https://members.lipscore.com/widgets  
    
   The correct API key needs to be automatically filled out in the Initializer script. 

Note: if your platform offers solutions for multistores (multiple webstores can be handled in one account), make sure to include a solution that allows using different API keys per store.

3. Interface locale (dropdown list) 
   Determines the language of Lipscore widgets displayed on the website. The locale selected here should update the Initializer script with the right language marking (see above). 

4. Product ID (dropdown list) 
   This is the identifier of the product that will be used in the order data sent to Lipscore, as well as in the Lipscore widgets. The customer should have a possibility to choose which ID they want to use as an identifier (platform-generated product ID, SKU, other). The default ID should be a parent ID, a product ID that has the same value for all variants of the product. 

5. Brand (dropdown list) 
   A dropdown list of available product fields that can be selected as the Brand attribute for the product. If the platform has one specific field for this, a configurable setting may not be necessary. 

6. GTIN (dropdown list) 
   A dropdown list of available product fields that can be selected as the GTIN attribute for the product. If the platform has one specific field for this, a configurable setting may not be necessary. 

7. Order status (dropdown list) 
   Order status is what triggers sending of data to the Lipscore system, normally values like Completed/Shipped/Sent/etc. When order is marked as Complete in the platform system, order data is sent to Lipscore and an invitation is created in our system. Invitation will be sent after a number of days specified by the customer in their Lipscore account. 

8. Active / Deactivated 
   Customers should be able to deactivate the module with a switch without having to uninstall. 

Frontend integration in the module 

The module needs to install the initializer script automatically based on the settings described above.  

Widgets library: https://members.lipscore.com/widgets  

Developing shortcodes for the various widgets is recommended but not a requirement. 

The themes used by customers differ, and so do their preferences regarding widgets placements, etc. Therefore as a rule, we only include 2-3 widgets in the automatic integration via app:  

• Rating widget – under product name on product detail pages 
• Small rating widget – on category pages / grid view 
• Review list widget – if possible to choose placement automatically 

Other widgets need to be added manually by customer’s or Lipscore developers, according to the customer’s preferences. 

Testing the module 

In order to test the functionality of the module you will need a Lipscore test account. Please contact [email protected] if you don’t have access to a test account already and we will help you set it up.  

Once you are ready to test the module you need to: 

1. Create an order on the testsite, preferably with a real name/email address 

2. Set the order in the right Order Status (the one you have configured in the module settings) 

3. If the order data transfer is working, you should see an Invitation scheduled in the Invitations page on your Lipscore test account: 

4. You should also be able to click Send Now on the invitation and it will be sent to the email address registered in the order data. Please be aware that some frontend installation (the initializer script as a minimum) is required for the full review process to work.  

5. If you have not done any frontend installation yet, you can still test the ratings / review creation process by enabling the Lipscore-hosted review landing page: 
    

Verification process 

Once the module has been tested by you and seemingly works as expected you need to schedule a module verification session with Lipscore before it can be released. During this process we will verify the following: 

• Go through the setup process as if we were the webshop 
• Check that the invitation is scheduled upon the right order status. 
• Check in our database that the right data is sent to us. 
• Check that the initializer script has been correctly injected.  
• Test the entire reviewing process from start to finish. 
• Test widgets for aesthetics and functionality (if any)  

If you have any issues or questions, please contact us for help.

[email protected] 

Good Luck 😊