Designer Tool Plugin Integration

What is the Designer Tool?

Perso Design Services offers an industry-leading fully-responsive HTML5 Designer Tool that can be integrated directly into the issuer's web or mobile app, enable cardholders to design their card seamlessly within the issuer's brand experience.

The framework being used around the plugin allows for a fast single page designer application using a single concatenated and minified JavaScript file that can be easily embedded within any of an Issuer's web pages or mobile app.

Features

• Single page application (no page loads)

• Fully Stateless

• Seamless integration

• Enhanced performance

• Responsive and customizable

• Advance state management

• Callbacks (changeView)

Flow Diagram

Host Page

Your host page must contain the elements below.

HTML5 Responsive Designer placeholder

The placeholder will typically reside in a container element. The container element can be placed alongside your own branding and other elements. The designer is programmed to fill this container (within specified limits) such that a responsive design experience can be achieved, displaying correctly over a range of devices and screen-sizes.

<div id="aam-designer" class="aam-designer-init" data-handoverkey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"></div>

Product Handover Key

A product must be setup in the AllAboutMe/SketchMyCard Adniministration Dashboard with access to the HTML5 features enabled. This will create a unique GUID that needs to be added as the value for “data-handoverkey” in the designer placeholder above.

JavaScript Source

Reference to the minified designer file (embed.min.js) on our servers. As part of the project implementation, a different “src” URL will be supplied for UAT and Production to the specific HTML5 Skin that has been agreed upon. This URL will point to a specific JavaScript file which will hold information about the current functionality and look and feel of the designer.

<script type="text/javascript" src="xxxxxxx.js"></script>

Reference to the parameter options file (appParam.js).

<script type="text/javascript" src="appParams.js"></script>

Provisional Extra: Stylesheet Source

The designer can be linked to:

• A default stylesheet

<link href="xxxxxxx/embed.min.css " rel="stylesheet">

• Your own custom stylesheet, which can be added to your host page’s folder.

<link href="embed.min.css" rel="stylesheet">

This will enable the designer to be displayed using modified styling of your choice (subject to limitations)

appParams.js file

The appParams file exists alongside your host-page and contains various configuration options:

const designer = new aam.designer({

    callbacks: {
        onLoad: function () {
            console.log('Designer loaded');
        },
        onSubmit: function (response) {
            console.log("onSubmit =======! " + response);
            // do something with onSubmit callback
        },
        onError: function (response) {
            console.log(response);
        }
    },

    options: {
        detectMobile: true,
        languageId: ‘en- US’,
        emailAddress: '[email protected]',
        passthrough: {
            // Optional Parameters
            param1: “Anything you like”
        },
        startHidden: false, // boolean
        handback: {
            url: "https://www.yourhandbackurl.com/"
        }
    }
});
designer.start();

Callbacks

• onload: executes when the plugin has loaded (when API is available)

• onSubmit: executes when the user has submitted the design (handback data is returned here). Information about the design session can be accessed after the onSubmit callback is fired using the following:

  • “response.CardImageId” will return a unique CardImageId associated with the submitted design.

  • “response.Handover_Key” will return the product HandoverKey.

  • “response.ImageType” will return the type of image that an end user submitted during the design process. These values can be “Gallery” or “Custom”.

  • “response.LanguageId” will return the language code that was used when displaying the designer which can be the default value setup in the product or a language code passed into the designer. Example codes “en-US”, “fr-FR”, etc.

  • “response.emailaddress” will return the email address of the end user that was captured

• onError: executes when an error has occurred (error info is returned here).

• onViewChange: executes when view has changed.

Including CardHolderID

An anonymized issuer-defined CardHolderID can be included as a handover parameter upon loading the Designer Tool. This enables Thales to provide more accurate usage reporting, as we can determine unique user sessions and designs, while still requiring zero information that personally identifies end users.

• The designer is loaded with a query parameter, where:

  • Key name = CardHolderID (or other key name as set up in Product Settings in the Administration Dashboard).

  • Value = CardHolderID value.

• This key–value pair is passed in the request payload.

• If the query parameter key name does not match the stored key name → value is ignored.

• If the key name matches → value is processed and persisted in the database enabling later reporting.

Options

Please Note: Any options that are used during the launch of the HTML5 Responsive Designer Tool will override the default options already configured at Product level.

• startHidden: Designer is not displayed until all of its components have loaded.

• env: can differentiate environment from which designer is referenced (please get in touch with Thales AAM team for specific values).

• languageId: Allows for the AAM HTML5 Responsive Designer to be loaded using a different language other than the value setup by default in the AAM Product configuration page.

• passthrough: optional parameters can be passed into the designer session to be passed back to the Handback page after design submission. These key:value pairs would also be stored as DataCapture values if this have been setup within Program Management. Example:

passthrough: {passthroughParameter:'passthroughValue'},

• handback: Allows the use of Dynamic Handback URLs where by different end users can be redirected to different handback pages. Commonly used to handback to multilingual pages. This is used with conjunction with the AAM product URL whitelist that ensures only validated handback URLs defined are allowed to be used.

  • url: Full URL set to redirect the page after the a design submission.

Other options (and/or added in the future) may be available depending on the chosen designer skin type.

Language

The designer uses text loaded from a central source at run-time, such that multiple languages can be used (see Options). Languages can be specified on a per-product basis.

Controlling Embedded Plugin-designer Dimensions

The following meta-tags should be added to the tag to optimize the responsive behaviour on mobile devices:

<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="apple-mobile-web-app-capable" content="yes">

By default, the plugin-designer is set up to fit its container (as shown in red below) but with upper and lower limits:

• Mobile devices:

  • min height: 320px max height: none

  • min-width: 320px max width: none

• Desktop devices:

  • min height: 560px max height: 590px

  • min width:320px max width: 1000px

<div id=”yourContainer”>
    <div id="aam-designer" class="aam-designer-init" data-handoverkey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"></div>
</div>

The aim is to enable you to display your own branding and content alongside the designer where space allows.

For the best results, the designer’s container should match these values, however an alternative is to add the ‘fullscreen’ class to the designer tag as shown below. This will allow the designer to expand the size of the browser window for both mobile and desktop platforms.

<div id=”yourContainer”>
    <div id="aam-designer" class="aam-designer-init fullscreen" data-handoverkey=" xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx">
    </div>
</div>