> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/perso-design-services/implement-allaboutme-and-sketchmycard-b2c/integrate-designer-tool/designer-tool-plugin-integration.md).

# 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 <a href="#toc56694811" id="toc56694811"></a>

* Single page application (no page loads)
* Fully Stateless
* Seamless integration
* Enhanced performance
* Responsive and customizable
* Advance state management
* Callbacks (changeView)

### Flow Diagram

<figure><img src="/files/qwLPlui0CR4lCmdzAI2u" alt=""><figcaption></figcaption></figure>

### Host Page <a href="#toc56694814" id="toc56694814"></a>

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.

```html
<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 <a href="#toc56694817" id="toc56694817"></a>

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.

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

&#x20;Reference to the parameter options file (appParam.js).

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

### Provisional Extra: Stylesheet Source

The designer can be linked to:

* A default stylesheet

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

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

```html
<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:

```javascript
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: 'test@test.com',
        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:

```javascript
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:

```html
<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

```html
<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.

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payments.thalescloud.io/perso-design-services/implement-allaboutme-and-sketchmycard-b2c/integrate-designer-tool/designer-tool-plugin-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.