WIDGET PEM Usage and Integration Guide

production and sendbox environments

Premium Partner doc. widgetV205a.doc

Release data 19/02/2022 V205a

Our PEM WIDGET has been developed specifically to be flexible to the most common cases of implementation and method of use by the end user.

In order to use our PEM WIDGET it is necessary to have contacted the sales department that will provide the activation codes.

PEM WIDGET can be configured to work in Sale, Free, Mixed mode, with photos uploaded by the user (User generated) or in Locked mode (Costumer Locked), where images/photos are pre-loaded by the integrator and the user can choose only among those proposed.

Apparently complex, our Widget is normally installed in a few minutes. Our technical department, once obtained the necessary information, will provide the code to “copy and paste” directly into your page and the PEM WIDGET will be already working and active. Possible configurations, variations of use, useful for example in specific events or on special dates and anniversaries, can be modified directly by the integrator by reading this documentation.

This comprehensive documentation allows developers to integrate and optimize our PEM WIDGET by familiarizing themselves with the parameters and customizations.

At the end of this document you can also access test environments or download example items.

What do you need to communicate to Pemcards to activate the WIDGET PEM?

In order to activate the PEM WIDGET on your website you need to obtain the Token ID and Application Brand (UIID).

To obtain the Token ID and Application ID, the customer must provide Emotion with the following information :

a) Installation domain (it is sufficient the domain and not the specific page)

b) In case of sale of credits (PEMCOIN) indicate which product you intend to sell, for example: 1 credit, 3 credits, 5 credits, 10 credits. Each PEM WIDGET can have “n” different products. In the free word mode (PEMCODE), the word must be indicated and must be all in capital letters, minimum 5 characters maximum 15 characters and cannot have already been used by other our clients.

c) Installation start date and duration. This information is managed by the commercial office. The PEM WIDGET can be installed and remain active for 1 month, 3 months, 6 months, 12 months.

d) 700x200px sponsor banner that will appear on the back of the postcard.

e) Optionally, logo of 150px x 150px that will be automatically inserted on the front of the postcard both in preview and in the printing process.

f) Optionally, customCSS (see paragraph) to customize the style of the widget.

Token Activation

The customer who decides to integrate the widget will have to indicate the site(s) on which it will be installed. The modalities of implementation, purpose and duration are regulated by the individual commercial agreements between the parties and by the agreement of the “Terms of use”.

Environment

Two end-point environments are available, one for testing the widget (test environment), the second for production (production environment).

Each environment uses different Token IDs, it is not possible to use Token IDs created for the test environment in production environments and vice-versa.

  • Test environment (SendBox): allows you to test the operation of postcard creation and sending to our backend. All postcards received on the test environment will not be printed and sent. The credits used will not be counted.
  • Production environment: All postcards received on the production environment will be processed, printed and shipped. Credits used will be counted with the related cost.

General Information
The Pemcards widget is written in pure javascript, so it can be included in any web application. At the moment, no conflicts with other known libraries or frameworks have been detected.

The widget uses a CDN for static content distribution and an endpoint for operations related to user management and postcard creation.

Token ID – provided by Emotion

The security and authenticity of the widget is achieved through the use of a JWT (json web token), which allows to validate from which domain the requests to the endpoint arrive and verify that the widget is used in a site authorized by Emotion.

Each token, provided by Emotion, will be verified and validated at each initialization:

  • website (domain) on which the widget is installed
  • validity date of the Token ID
  • destination end-point (if production or test)

at each variation of one of the above elements, the token must be replaced within its code with a new one.

Application Brand (UIID) – provided by Emotion

The application brand (UIID) is a special code that allows the integrator to install a widget on different pages and/or from one or more domains using the same Token ID but leaving the integrator free to define which brand should be printed on the back of the card.

Widget Graphic Layout

Graphic customization

A – the PEM Widget can be installed in your website

1 – headerImage is a banner image with dimension 677x137px jpg or png format.

2 – user, the widget can be used with silent authentication (i.e. the integrator already knows the user) or in registration mode

3 – showBannerInfo, shows an informative banner on how to use the PEM WIDGET. It is possible not to show it when opening the PEM Widget or it can be closed manually by the user.

4 – Upload area, this area allows the end users to upload their own photo or take a photo from their smartphone. It is however possible to lock this mode and switch to “Locked” mode, the end user can only use images defined by host.

5 – Custom.css, you can customize the radius of the buttons and the primary colors used in the widget to have a greater graphic coherence with your website. The customCSS is an external file that, if uploaded, overrides the default one.(see parameters table)

6 – hidefooter, hides the banner under the widget with the invitation to download the Pemcards application

Endpoint – Parameters

Endpoints to activate the widget

Test environment (SendBox) <script src=”https://d1nnlhsh6z98pp.cloudfront.net/js/main.js”></script>
Production environment <script src=”https://d2gnru2qokx8eq.cloudfront.net/js/main.js”></script>

Customizable widget parameters

Parameter Function Obbligatorio
id Id of the div in which the widget will be included. The parameter is “pemWidget” and must be unique. SI
token Token that identifies the widget. It will be provided by Pemcards SI
language

language of the widget. If not set the browser language or English will be used. Possible values

  • it → italian
  • en → English
  • fr → French (currently in translation)
  • de → German (currently in translation)
  • es → Spanish (currently in translation)
NO
user

The widget, if needed, allows to pass the user account in silent mode. This feature is usually used when the integrator already has the user’s registration data and does not want to have the user re-authenticate.

If not present in the widget initialization code, users will be able to log in/register directly in the platform.

It should be expressed as:

“user”: {

“email”: “carlo.rossi@myemail.com”,

“first_name”: “Carlo”,

“last_name”: “Rossi”

},

Note : only the email address is mandatory, however it is recommended to pass also the first and last name for helpdesk and support activities.

NO
headerImage** url of the image that will appear centrally in the widget header. If not present, a default image will be used. Banner 677x137px 72DPI .png or .jpg format NO

customCss**

(a copy of the modified CSS file will have to be sent to the technical support that will implement it in the Backend. This allows us to solve the problems of the CORS limits of the Browsers)

url of a css file to overwrite the existing graphic properties. An example file with all editable properties will be provided. Change the radius of the buttons and the primary colors of the widget to adapt it to the graphics of your website. NO
publicWorkstation if set to true, the widget will end the current session after 5 minutes. This function is particularly useful on computers that are used by more people ( e.g. workstations in hotel lobbies, totems, etc.). NO

frontLogo

(a copy of the modified CSS file will have to be sent to the technical support that will implement it in the Backend. This allows us to solve the problems of the CORS limits of the Browsers)

Logo that will appear at the top right corner on the front of the postcard. For best results, the logo must be a png with a size of 100x100px or 150x150px. NO
hideFooter Hides the banner under the widget with the invitation to download the Pemcards application NO
includeGoogleMapsJavascriptApi if set to false, the Google js file will not be loaded. To be used when the customer site already includes Google API. Verify that your API key MapsJavascriptApi and PlacesApi libraries are activated. NO

payment

(it is necessary to have determined with the commercial office which PEM COIN will be sold, e.g. 1 x credit, 4 credits, 8 credits etc.)

if set to True, it allows to enable the purchase credits directly from the widget NO
qrScan If set to True, enables the ability to acquire PEMCOIN (credits) provided in QRCode format. NO
brand Use the value provided by Pemcards to be able to specify the “Application brand” that will be displayed on the back of the postcard. It is provided by Pemcards SI
geolocationColor color of the geolocation printed on the front of the postcard. It should be expressed as an rgba string ‘rgba(43, 113, 208, 1)’ . Default is “red” NO
backGeolocation if set to True, the geolocation will appear on the back of the postcard instead of the front (and therefore will not be printed) but the data will be acquired by the PEMCARDS platform. NO
showBannerInfo if set to True, it shows a banner under the header that helps the user to understand the steps to create a postcard NO
backBannerImage Url of the banner on the back of the postcard. Valid only if no brand is specified. It is a special function, ask the technical department before using it NO

Images

(NEW FUNCTION – LOCKED MODE)

Allows you to set up the widget in Locked Mode where the images are pre-loaded. The end users will not be able to upload their images and will not be able to modify those provided by the host.
More than one image can be displayed using an array of image urls. In this case, at each opening the widget will display a different image.For optimal use, the images must have the same domain as the installed widget.”images”: [“https://mydomain.com/images/sfilata_01.jpg”,

“https://mydomain.com/images/sfilata_02.jpg”,

“https://mydomain.com/images/sfilata_03.jpg”

]

NO

** where not specified otherwise the url are always absolute

Inclusion of the widget in the page

The widget is designed to be easily integrated without having to develop code by the integrator and is based on three elements:

a) Inclusion of a javascript file (production/test)

<script src=”https://endpoint(productionorsendbox).cloudfront.net/js/main.js”></script>

This file, distributed via cdn, contains the widget initialization logic and loads all the files (javascript and css) needed to render the widget.

b) Embedding a div [div and not iframe]

<div class=”pemWidget” id=”pemWidget”></div>

In the html page we need to include a div with class pemWidget and a unique id. Inside this div the widget will be created.

N.B. for an optimal use, the widget must be included directly in the page where it will be used, avoiding the use of iframe.

c) Execution of a javascript function

<script>

PemMain.init({

“id”: “pemWidget”,

“token”: “your Pem-Token ID”,

“brand”:”uuidd your Pem-brand ID”,

…. (Customizable widget parameters. This script takes care of the actual initialization of the widget, for details about the parameters see the initialization table).

Nota bene il widget utilizza diverse modali che sono ancorate per un funzionamento corretto a full page. In caso di integrazione in siti usando wordpress o altre piattaforme, si consiglia di inserire il widget in una pagina dedicata e verificare comunque le modali così come che il .css del template non sovraN.B. the widget uses several modals that are anchored for proper operation to full page. In case of integration in sites using wordpress or other platforms, it is advisable to embed the widget in a dedicated page and still verify the modals as well as that the .css of the template does not overwrite that used in the widget. In some cases, the header or footer can create display problems. Position the widget correctly with the respective padding

Samples codes to use

Example of integration in Production – Postcards User Generated mode + active payment

<!DOCTYPE html>
<html lang=”it”>
<head>
<meta charset=”UTF-8″ />
<meta name=”viewport” content=”width=device-width, initial-scale=1.0″ />
<title>Pemcards Credits</title>
</head>
<body style=”margin: 0; background: url(https://yourdomain.com/backgroundpage.jpg) no-repeat center top fixed; background-size: cover;”>
<script src=“https://d2gnru2qokx8eq.cloudfront.net/js/main.js“></script>
<div class=”pemWidget” id=”pemWidget” style=”background: transparent;”>
</div>
<script>
PemMain.init({
“id”: “pemWidget”,
“language”: “it”,
“payment”: true,
“showBannerInfo”:true,
“qrScan”:true,
“headerImage”: “https://yourdomain.com/header_image.jpg“,
“hideFooter”: true,
“token”: “your Pem-Token ID“,
“customCss”: “https://yourdomain.com/yourcss.css“,
“publicWorkstation”: true,
“geolocationColor”: ‘rgba[43,113,208,1]’,
“brand”:”uuidd your Pem-brand ID“,
});
</script>
<div style=”background-color: #6300A5; padding: 30px 0 20px; text-align:center; font-family: Montserrat, Arial, sans-serif;”><a style=”color:#ffffff; font-size: medium; text-decoration: none; border:2px solid #ffffff; padding: 5px; border-radius:3px;” href=”https://yourdomain.com/”>Back to website</a><p style=”color:#ffffff; text-align:center; margin-top:35px;”>Innovative Marketing User Generated</a></p></div>
</body>
</html>

Example of integration in SandBox – Mode Images Locked + payment disabled

<!DOCTYPE html>
<html lang=”it”>
<head>
<meta charset=”UTF-8″ />
<meta name=”viewport” content=”width=device-width, initial-scale=1.0″ />
<title>Pemcards Images Locked</title>
</head>
<body style=”margin: 0; background: url(https://yourdomain.com/backgroundpage.jpg) no-repeat center top fixed; background-size: cover;”>
<script src=”https://d1nnlhsh6z98pp.cloudfront.net/js/main.js“></script>
<div class=”pemWidget” id=”pemWidget” style=”background: transparent;”>
</div>
<script>
PemMain.init({
“id”: “pemWidget”,
“language”: “it”,
//”payment”: true,
“showBannerInfo”:true,
“qrScan”:true,
“headerImage”: “https://yourdomain.com/header_image.jpg”,
“hideFooter”: true,
“token”: “your Pem-Token ID“,
“customCss”: “https://yourdomain.com/yourcss.css“,
“publicWorkstation”: true,
“geolocationColor”: ‘rgba[43,113,208,1]’,
“brand”:”uuidd your Pem-brand ID“,
“images”:[
“https://yourdomain.com/images/photo_1.jpg”,
“https://yourdomain.com/images/photo_2.jpg”,
“https://yourdomain.com/images/photo_3.jpg”
]
});
</script>
<div style=”background-color: #6300A5; padding: 30px 0 20px; text-align:center; font-family: Montserrat, Arial, sans-serif;”><a style=”color:#ffffff; font-size: medium; text-decoration: none; border:2px solid #ffffff; padding: 5px; border-radius:3px;” href=”https://yourdomain.com/”>Back to website</a><p style=”color:#ffffff; text-align:center; margin-top:35px;”>Innovative Marketing User Generated</a></p></div>
</body>
</html>
Operating notes regarding registration

Integration of the code in the options where the login is required or in case of silent registration (i.e. it is the partner who passes us the user’s email).

A user who will be registered in the WIDGET will be registered with the same email and password also in the APP.

A user who will be registered in APP will also be registered in WIDGET.

A user who is registered in the platform with Facebook, will be recognized both on the WIDGET and in App.

Operating notes regarding credits

The use of credits from PEMCARDS APP or PEM WIDGET follow some precise rules.

Credits created for the PEM WIDGET can only be uploaded to the user profile from the associated WIDGET. Only when uploaded to the user profile, they will be available in both the App and the WIDGET.

Credits created for use in the App can only be validated and loaded by the PEMCARDS APP but once acquired in your profile they are also available in PEM WIDGET.

Credits generated for a specific PEM WIDGET cannot be validated by other PEM WIDGETs. Once acquired and associated to the customer they will be available in other PEM WIDGETs and PEMCARDS APP .

(Es. nel WIDGET carico un codice dal valore di 3, ne uso 1 per la spedizione, avrò un residuo di 2 crediti sia nel WIDGET specifico, che in tutti gli altri WIDGET che nell’App se si utilizzerà lo stesso account registrato.)

Credits generated for Validated by APP Validated by WIDGET Used for sending by APP Used for sending by WIDGET
PemCODE – for APP V X V V
PemCODE – for Widget X V V V
PemCOIN – for APP V V V V
PemCOIN – for Widget V V V V

N.B. It is possible to have the postcards printed with the banner associated to the widget, independently from who provided the credit, for more information ask the technical support.

Documents and sample environments

Example integration in Production: user generated photo + payment

Real environment with payment postcards mailing

https://pemcards.com/postcards
Example integration in SandBox: user generated photo + payment (does not finalize) https://pemcards.com/freetrial-it
Example integration in SandBox: Images Locked + NO Payment https://pemcards.com/image-locked-demo
Example integration in SandBox: Images Locked + Payment (does not finalize) https://pemcards.com/event-mode

for SandBox environments you can register with your email and use the free code TRYME2022

File CSS custom https://www.pemcards.com/docu-widget/custom.css
Header banner example
Example banner printed on the back postcard

Technical Support

1 + 2 =

Share This