Positive Luxury Integration Guide

Positive Luxury – Integration Guide – v4.0 Page 1 of 22

Positive Luxury Integration Guide v 4.0


Table of Contents

Introduction .................................................................................................................... 3

Web Integration .............................................................................................................. 3

The Trustmark JavaScript Include ............................................................................................. 3

Logical Flow ............................................................................................................................. 3

Trustmark DIV.......................................................................................................................... 4 Example ..........................................................................................................................................................4 Attributes ........................................................................................................................................................4 Additional Attributes ......................................................................................................................................5

Trustmark JavaScript Snippet ................................................................................................... 5

Complete Example Snippet....................................................................................................... 6

The Trustmark Default Web UI ................................................................................................. 6 Example Web UI .............................................................................................................................................6

Error Behaviour ....................................................................................................................... 8

Payload and Load Times ........................................................................................................... 8 File Sizes and Average Load Times .................................................................................................................9

Web Platform Integrations ....................................................................................................... 9 Shopify ............................................................................................................................................................9 Squarespace................................................................................................................................................. 11 Magento CMS .............................................................................................................................................. 12

Mobile App Integration...................................................................................................15

The Trustmark API ................................................................................................................. 15

Logical Flow ........................................................................................................................... 15

Available Methods ................................................................................................................. 15 Brand Actions............................................................................................................................................... 15 Butterfly Clicked .......................................................................................................................................... 16 Action Clicked .............................................................................................................................................. 16

Example Requests & Responses.............................................................................................. 18 Brand Actions............................................................................................................................................... 18 Butterfly Clicked .......................................................................................................................................... 19 Action Clicked .............................................................................................................................................. 20

Example App UI ..................................................................................................................... 21


Introduction This guide is designed as a technical integration document to aid development teams in the inclusion of the Positive Luxury Butterfly Mark in their websites and mobile apps.

Web Integration The Trustmark JavaScript Include Website integration is achieved by using the Trustmark JavaScript Include. This include will download all dependencies from the Positive Luxury Trustmark servers, will define the default UI for the Butterfly Mark overlay and will apply listeners to allow user interaction with the Butterfly Mark itself. Note that for ALL integrations, Positive Luxury now recommends that the data-nojquery=”true” parameter is always added. See the “Trustmark DIV” section below for details.

Logical Flow 1. Trustmark DIV defined in the Website’s HTML along with relevant Brand and Retailer

names, slugs, or aliases 2. Trustmark JavaScript Include added to the Website’s HTML and bound to the

Trustmark DIV 3. Document Load 4. Trustmark JavaScript Include automatically invoked and dependencies downloaded

from the Positive Luxury Trustmark servers including: a. Trustmark JavaScript b. jQuery c. Butterfly Mark Icon (light or transparent PNG) d. Butterfly Mark Icon (dark colour PNG for onHover events) e. Trustmark CSS f. Associated Trustmark Fonts

5. Trustmark JavaScript connects to the Trustmark server to collect data for the relevant Brand and Retailer

6. If the relevant Brand and Retailer names, slugs, or aliases are found, the Butterfly Mark Icon is displayed (see Error Behaviour below)

7. Trustmark View ajax tracking request sent to Positive Luxury tracking servers 8. Butterfly Mark onClick Event

a. Butterfly Mark Panel UI generated and displayed containing: b. Generic messaging about the Butterfly Mark scheme and the brand c. Specific Positive Action icons for the selected brand

9. Positive Action Icon onHover Event a. Positive Action Descriptive Bubble shown b. Positive Action Engagement ajax request sent to Positive Luxury tracking

servers


Trustmark DIV This is a DIV placed in the HTML wherever the Butterfly Mark should appear.

Example <div class="pl-trustmark" data-size="small" data-style=”dark” data-brand="Kiehls"

data-retailer="Brown Thomas" data-nojquery="true"></div>

Attributes

• class o [Required] o The class name of the DIV, used by the Trustmark JS snippet for binding

• data-size o [Optional] o Sizing of the Butterfly Mark Icon

• (empty / not defined) o Butterfly Mark shown at 90 x 90px

• “small” o Butterfly Mark shown at 60 x 60px

• “x-small” o Butterfly Mark shown at 30 x 30px

• data-style o [Optional] o Image colour for Butterfly Mark Icon

• (empty / not defined) o Butterfly Mark shown with white body

• “dark” o Butterfly Mark shown with black body

• “transparent” o Butterfly Mark shown with transparent body

o Note that all Butterfly Mark styles will use the black body when hovered over

• data-brand o [Required] o The name, slug, or alias for the brand being shown (e.g. “Krug”)

• data-retailer o [Required if client is a retailer] o The name, or slug for the retailer (e.g. “Brown Thomas”)

• data-nojquery o [Optional] o Determines whether the Butterfly Mark should include and use its own jQuery

package. o This is useful for sites which already use jQuery, as it can be used to prevent

the Butterfly Mark from importing its own jQuery and causing any potential conflicts.

• (empty / not defined) o Butterfly Mark will include its own jQuery package

• “false” o Butterfly Mark will include its own jQuery package


• “true” o Butterfly Mark will not include its own jQuery package o This is the recommended setting for any sites that already use

jQuery

Additional Attributes Any additional attributes will be ignored by the Trustmark JavaScript Include, allowing clients to apply inline styles, IDs, or other types of data.

Trustmark JavaScript Snippet This is a script tag snippet, normally placed directly after the Trustmark DIV. Note that this references the class of the Trustmark DIV as its final parameter, so these must match.

<script>(function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(d.getElementById(id)){return;}js=d.createElement(s);js.id=id;js.src='http://trust.p oslux.com/trustmark.js';fjs.parentNode.insertBefore(j

s,fjs);})(document,'script','pl -trustmark');</script>


Complete Example Snippet <div class="pl-trustmark" data-size="small" data-brand="Kiehls" data-retailer="Brown

Thomas" data-nojquery="true”></div>

<script>(function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(d.getElementById(id)){return;}js=d.createElement(s);js.id=id;js.src='http://trust.poslux.com/trustmark.js';fjs.parentNode.insertBefore(j


The Trustmark Default Web UI The default web UI for a Butterfly Mark is injected directly into the document, so its elements can be directly manipulated by clients if needed. Note that “!important” declarations may be needed to override some of the Butterfly Mark’s styles due to the on-demand loading of the Trustmark CSS. An additional SPAN node with the class “PL-mark” is injected into the Trustmark DIV. This contains the Trustmark Icon. An additional DIV node is injected into the page with the class “PL-modal”. This contains the Butterfly Mark Panel UI and is hidden until the Butterfly Mark is clicked.

Example Web UI

Figure 1 – Butterfly Mark Displayed with Associated Product


Figure 2 – Butterfly Mark Displayed with Associated Product (Hover)

Figure 3 – Butterfly Mark Panel Showing Associated Positive Actions


Figure 4 – Butterfly Mark Panel Showing Associated Positive Actions (Hover)

Error Behaviour If a brand or retailer is not found in the Positive Luxury database, a 404 response will be returned to the Trustmark JavaScript include and the Butterfly Mark Icon will not be shown.

Payload and Load Times The Trustmark JavaScript Include comprises of the following files which are requested from Positive Luxury’s servers:

1. trustmark.js o The main Trustmark functionality

2. jquery.min.js o jQuery Dependency (only included when the data-nojquery attribute is not

defined or is set to false) 3. trustmark.css

o Base styling for the Trustmark 4. trustmark.png

o The image which forms the Trustmark button 5. trustmark-dark.png

o The image which appears when the Trustmark button is hovered-over by the user


File Sizes and Average Load Times Note that Average Load Times are calculated using a standard broadband connection of ~48.5 Mb/s.

File Name File Size Load Timing Average Load Time Notes

trustmark.js 3.4 KB After page load 160 ms

jquery.min.js 32.8 KB After page load 80 ms

Only included when data-nojquery attribute is not defined or is set to false

trustmark.css 1.7 KB After page load 44 ms

trustmark.png 17.9 KB After page load 57 ms

trustmark-dark.png

142 KB On mouse hover over Butterfly Mark

216 ms

Web Platform Integrations There are many web platforms available on the market now, and each has their own specific methods for integrating web includes such as the Butterfly Mark. In the first instance, please refer to your web platform’s documentation for the inclusion of JavaScript and additional HTML, but we have outlined how to integrate with some of the most popular platforms below. Note that for ALL integrations, Positive Luxury now recommends that the data-nojquery=”true” parameter is always added. See the “Trustmark DIV” section above for details.

Shopify The best way to integrate with Shopify, is to edit your theme. Here’s how to do that.

• Go to your theme settings in your Shopify Admin and make a backup of your theme by either duplicating it or download it as a theme file


Screenshot showing Shopify Theme Admin. Note the Actions Button allows you to Duplicate, Download or Edit your Theme

• Select “Edit code” from the Actions Button to enter the Theme Editor.

• Select the main theme file (theme.liquid) from the navigation on the left-hand side to open it in the Theme Editor

• Paste your Butterfly Mark code into the Theme Editor wherever you would like the Butterfly Mark to appear. This is normally best just above the footer, which you will see as {% section ‘footer’ %} in the Theme Editor

Screenshot showing Shopify Theme Editor with theme.liquid selected, and the Butterfly Mark code inserted just above the footer.


Layout Tip When you insert the Butterfly Mark, depending on how your theme works you might find that it sits on the left-hand side of the screen. If you’d like to center the Butterfly Mark on the screen, try adding the following code to your Butterfly Mark:

style="width:100%;text-align:center;margin-top:80px;" So, in this case the full Butterfly Mark code would look like this:

<div class="pl-trustmark" data-size="small" data-brand="Your Brand" data-retailer="Your Retailer" style="width:100%;text-align:center;margin-top:80px;" data-

nojquery="true”></div>

<script>(function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(d.getElement ById(id)){return;}js=d.createElement(s);js.id=id;js.src='http://trust.poslux.com/trustmark.js';fjs.parentNode.insertBefore(j


• Save your Theme by pressing the Save button at the top-right of the Theme Editor.

• Check your site and you should now see your Butterfly Mark appear at the bottom of each page, just above the footer.

Squarespace Squarespace limit the number of things that you can do in their standard package, so in order to integrate the Butterfly Mark, you will need a Premium Plan so that you can add JavaScript to your site. With Squarespace you will need to create a Code Block wherever you want the Butterfly Mark to appear. You can add a Code Block to individual posts and pages, or to something like the footer so it will appear on every page of your site. Note that some template families such as Bedford and Pacific, also have a “Pre-footer” which appears above the footer where you could put the Butterfly Mark instead.

Creating A Code Block Code Blocks are added just like any other block in Squarespace.

• Just edit the page, post, footer or pre-footer, click an insert point and select “Code” from the menu.

• Paste your entire Butterfly Mark code into the Code Block.

• Ensure that the Code Type (at the top-right) is set to “HTML”, and that the “Display Source” checkbox (at the top-left) is NOT checked.


Screenshot showing a Squarespace Code Block containing the full Butterfly Mark code

• Click Apply and your Code Block will be saved to your page, post, pre-footer or footer.

• Check your site and you should now see your Butterfly Mark appear wherever you have added the Code Block.

For more information on Code Blocks, see this page on Squarespace’s Support Site which includes a short walkthrough video of how they work:

https://support.squarespace.com/hc/en-us/articles/206543167

Magento CMS For Magento, the best method is to create a custom Block which can be re-used across the site wherever you want the Butterfly Mark to appear.

Creating a Custom Block

• On the Admin sidebar, go to Content > Elements > Blocks

• In the upper-right corner, click Add New Block. Then, do the following:

• In the Block Title field, give the block a name such as PL_Block.

• In the Identifier field, give the block an identifier such as PL_Block.

https://support.squarespace.com/hc/en-us/articles/206543167


• Choose the Store View where the block is to be available.

• In the editor below these fields, ensure that “Show/Hide Editor” is set to “Hide” so you can input JavaScript and HTML.

• Paste your entire Butterfly Mark code into editor area.

• In the upper-right corner, Save the settings and return to the Page Builder workspace.

Screenshot showing Magento Block creation and the full Butterfly Mark code included

Adding the Block to a Page

• On the Admin sidebar, go to Content > Elements > Pages

• Select a page where you would like to include the Butterfly Mark and select Edit in the Action column.

• Expand the Content section and scroll down to the Page Builder workspace.

• In the Page Builder panel, expand the Add Content section. Then, drag a Block placeholder to the new row.

• Hover over the empty Block container. Then, choose Settings in the toolbox.

• On the Edit Block page that shows, click Select Block and add the Butterfly Mark block that you created.


• In the upper-right corner, click Save to save the settings and return to the Page Builder workspace.

• In the upper-right corner on the Save menu, choose Save & Close to save your changes to the page.

For more information on creating and using Blocks, and for further information on the Page Builder, visit this page on Magento’s website:

https://docs.magento.com/m2/ee/user_guide/cms/page-builder-tutorial2-blocks.html

https://docs.magento.com/m2/ee/user_guide/cms/page-builder-tutorial2-blocks.html


Mobile App Integration Mobile app integration is achieved by directly accessing the Trustmark API which returns data related to brand’s Positive Actions, required images and provides endpoints for tracking interactions.

The Trustmark API The Trustmark API is accessed at https://api.poslux.com/api/brand-actions/ and requires a pre-shared key in order to authenticate requests. This pre-shared key will be provided to you by Positive Luxury and is distinct for each app OS (e.g. iOS, Android).

Logical Flow 1. The user views a specific brand or product in the client’s app 2. The app performs a request to the Trustmark API to determine whether this brand is

registered with Positive Luxury, and if so, the Positive Actions associated with it and the relevant icons and text

3. The app displays the Butterfly Mark if this brand is registered with Positive Luxury 4. The user taps the Butterfly Mark 5. The app displays a panel showing the Positive Actions for this brand 6. The app performs a request to the Trustmark API to track this interaction with the

Butterfly Mark (a “Butterfly Clicked” event) 7. The user taps a Positive Action 8. Details of the Positive Action are shown to the user 9. The app performs a request to the Trustmark API to track this interaction with the

Positive Action (an “Action Clicked” event)

Available Methods

Brand Actions

• GET

• https://api.poslux.com/api/brand-actions/{brand-slug}

• {brand-slug} o The slug associated with the brand

• Headers o access-token

▪ The pre-shared key for this retailer and OS (40-character string)

• Returns o Brand Found

▪ 200 OK ▪ JSON Array of Positive Actions for the requested brand slug

o Brand Not Found ▪ 404 Not Found ▪ JSON Object containing an error message

o Unauthorised ▪ 401 Unauthorized ▪ JSON Object containing an error message

• Average Return Payload o Size: 1KB


o Average Response Time: 200 ms

Butterfly Clicked

• POST

• https://api.poslux.com/api/brand-actions/{brand-slug}/butterfly-clicked/{user-id}


• {user-id} o If known, the ID of the current app user. This is available to aid tracking and

metrics and is required. If this is not known, then “0” should be sent.

• Headers o access-token

▪ The pre-shared key for this retailer and OS (40-character string)

• Returns o Successful

▪ 200 OK ▪ JSON Object containing a success message

o Unauthorised ▪ 401 Unauthorized ▪ JSON Object containing an error message

• Average Return Payload o Size: 243 bytes o Average Response Time: ~100 ms

Action Clicked

• POST

• https://api.poslux.com/api/brand-actions/{brand-slug}/action-clicked/{user-id}


• {user-id} o If known, the ID of the current app user. This is available to aid tracking and

metrics and is required. If this is not known, then “0” should be sent.

• Headers o access-token o The pre-shared key for this retailer and OS (40-character string)

• Form Body o x-www-form-urlencoded

▪ Key: “action” ▪ Value: The name of the Positive Action that has been tapped by the

user, as defined in the “title” property of the Positive Action returned in the call to the Brand Actions method (e.g. “Reduces Waste”)

• Returns o Successful

▪ 200 OK ▪ JSON Object containing a success message

o Unauthorised


▪ 401 Unauthorized ▪ JSON Object containing an error message

• Average Return Payload o Size: 243 bytes o Average Response Time: ~100 ms


Example Requests & Responses

Brand Actions

Example Request G E T / a p i / b r a n d - a c t i o n s / k r u g H T T P / 1 . 1 H o s t : a p i . p o s l u x . c o m a c c e s s - t o k e n : p E y Q A h 1 7 4 B M 6 Q 5 N b 3 q Y 9 9 C f 8 s i y 9 l k X 5 b p v w 1 2 3 4 C a c h e - C o n t r o l : n o - c a c h e

Example Responses

Headers C o n n e c t i o n : k e e p - a l i v e C o n t e n t - E n c o d i n g : g z i p C o n t e n t - L e n g t h : 7 7 4 C o n t e n t - T y p e : a p p l i c a t i o n / j s o n ; c h a r s e t = u t f - 8 D a t e : T u e , 2 5 M a r 2 0 1 8 1 8 : 2 6 : 2 8 G M T E T a g : W / " 7 a a - w t M o 4 k c g V e t s J 5 z 9 f 6 r r 1 2 " S e r v e r : n g i n x / 1 . 1 0 . 2 X - P o w e r e d - B y : E x p r e s s

Body (Brand Found – 200 OK) [ { " t i t l e " : " V D C C e r t i f i e d " , " t e x t " : " C e r t i f i e d b y V i t i c u l t u r e D u r a b l e e n C h a m p a g n e f o r e n v i r o n m e n t a l f a r m i n g & w i n e g r o w i n g i n C h a m p a g n e , F r a n c e " , " i c o n " : " h t t p s : / / p o s l u x -p r o d u c t i o n . s 3 . a m a z o n a w s . c o m / i n f o g r a p h i c s / V D C _ C E R T I F I ED - 0 1 . p n g " } , { " t i t l e " : " R e d u c e s W a s t e " , " t e x t " : " A i m s t o r e d u c e m a n u f a c t u r i n g w a s t e " , " i c o n " : " h t t p s : / / p o s l u x -p r o d u c t i o n . s 3 . a m a z o n a w s . c o m / i n f o g r a p h i c s / R E D U C E S _ W AS T E - 0 1 . p n g " } , { " t i t l e " : " R e d u c e s W a t e r " , " t e x t " : " H a s p u b l i c l y a v a i l a b l e w a t e r re d u c t i o n t a r g e t s " , " i c o n " : " h t t p s : / / p o s l u x -p r o d u c t i o n . s 3 . a m a z o n a w s . c o m / i n f o g r a p h i c s / R E D U C E S _ W AT E R _ U S E - 0 1 . p n g " } ]


Body (Brand Not Found – 404 Not Found) { " e r r o r " : { " m e s s a g e " : " B r a n d n o t f o u n d : k r u g " , " n a m e " : " B r a n d N o t F o u n d E r r o r " } }

Body (Unauthorised – 401 Unauthorized) { " e r r o r " : " F o r b i d d e n " }

Butterfly Clicked

Example Request P O S T / a p i / b r a n d - a c t i o n s / k r u g / b u t t e r f l y - c l i c k e d / 0 H T T P / 1 . 1 H o s t : a p i . p o s l u x . c o m a c c e s s - t o k e n : p E y Q A h 1 7 4 B M 6 Q 5 N b 3 q Y 9 9 C f 8 s i y 9 l k X 5 b p v w 1 2 3 4 C a c h e - C o n t r o l : n o - c a c h e C o n t e n t - T y p e : m u l t i p a r t / f o r m - d a t a ; b o u n d a r y = - - - -W e b K i t F o r m B o u n d a r y 7 M A 4 Y W x k T r Z u 0 g W

Example Responses


Body (Successful) { " s t a t u s " : " O k " }



Action Clicked

Example Request P O S T / a p i / b r a n d - a c t i o n s / k r u g / a c t i o n - c l i c k e d / 1 2 3 H T T P / 1 . 1 H o s t : a p i . p o s l u x . c o m a c c e s s - t o k e n : p E y Q A h 1 7 4 B M 6 Q 5 N b 3 q Y 9 9 C f 8 s i y 9 l k X 5 b p v w 1 2 3 4 C o n t e n t - T y p e : a p p l i c a t i o n / x - w w w - f o r m - u r l e n c o d e d C a c h e - C o n t r o l : n o - c a c h e a c t i o n = R e d u c e s + W a s t e

Example Responses


Body (Successful) { " s t a t u s " : " O k " }



Example App UI

Figure 5 – Butterfly Mark Displayed with Associated Product

Figure 6 – Butterfly Mark Panel Showing Associated Positive Actions


Figure 7 – Butterfly Mark Panel Showing Selected Positive Action

DOCUMENT ENDS

Date post:	31-Oct-2021
Category:	Documents
Upload:	others
View:	4 times
Download:	0 times

Positive Luxury Integration Guide

Documents