How to implement The Wallet Crew sdk "Add to wallet" button on your website?

Published:

Updated:

The Wallet Crew cinto SDK allows developers to add a “add to wallet” button on a website.

UI Result

On iOS mobile device

On Android mobile device

Otherwise

This button redirects the user to The Wallet Crew pass layout which looks like this :

How to display the button ?

Through vanilla javascript

<script type="text/javascript">
(function (n, e, o) {
var s=n.createElement("script");s.src="https://sdk.neostore.cloud/scripts/"+e+"/cinto@1";s.async=1;
s.onload=function(){neostore.cinto.initialize(e,o)};n.body.appendChild(s);
})(document, "molia", {});
</script>

<div data-neostore-addToWalletButton data-neostore-passId="KlnqcxVLA9pS4ol5"></div>

The third parameter may contains any option available for The Wallet Crew, to force a language use

<script type="text/javascript">
(function (n, e, o) {
var s=n.createElement("script");s.src="https://sdk.neostore.cloud/scripts/"+e+"/cinto@1";s.async=1;
s.onload=function(){neostore.cinto.initialize(e,o)};n.body.appendChild(s);
})(document, "molia", { language: "fr" });
</script>

<div data-neostore-addToWalletButton data-neostore-passId="KlnqcxVLA9pS4ol5"></div>

Through npm module

npm install @neostore/cinto

// install cinto SDK through npm install @neostore/cinto
import { AddToWalletButton } from "@neostore/cinto";

const btn = new AddToWalletButton("molia", {
    language: "fr",
    passId: "KlnqcxVLA9pS4ol5",
});
btn.render(document.getElementById("btn"));

Options

export interface Options {
    /**
     * Neostore URI environment to use.
     * @default: <https://app.neostore.cloud>
     */
    environment: string;
    /**
     * Identifier of the tenant.
     */
    tenantId: string;
    /**
     * Name of the pass layout to redirect the user when the user is on desktop
     * @default: pass
     */
    passLayoutName: string;
    /**
     * ISO 639 language code to use to do display the button. When omitted, the language will be automatically detected based on the browser settings.
     * If the value doesn't match any available option, the browser settings will be used otherwise english will be used.
     * @default: undefined
     */
    language?: string;
    /**
     * Identifier of the pass to display or promise of it
     */
    passId: string;
    /**
     * Platform to use to display the button. When omitted, the platform will be automatically detected based on the user agent.
     * Possible values are: "apple", "google" or "desktop"
     *
     * @default: undefined
     **/
    platform?: Platform;
    /**
     * External identifiers to use to aquire the passId
     */
    externalIdentifiers?: Record<string, { value: string; hmac?: string }>;
    /**
     * Pass type to use to aquire the passId
     * Required when externalIdentifiers is set
     */
    passType?: string;
    
    /**
     * Source used for analytics purpose
     */
    source?: {
        /**
         * list of tags to associate to this download. utm_source and utm_campaign will automatically be aggregated to this list
         */
        tags?: Array<string>;
        /**
         * medium to associate to this download. utm_medium will be used if no value is specified
         */
        medium?: string;
        /**
         * origin to associate to this download. the current url (without query) will be used if no value is specified
         */
        origin?: string;
    };

    /**
     * Callback called when the button is clicked
     */
    onClick?: (e: MouseEvent, data: { options: Partial<Options>; platform: Platform }) => void;

    /**
     * Callback when an error occurs
     *
     */
    onError?: (error: string) => void;
}

Concepts

Platform detection

When using the data-neostore-addToWalletButton data attribute, the component will automatically render the right button with the defined callback:

desktop: redirects to the pass page from The Wallet Crew
apple: displays the add to wallet call to action that downloads the pass
android: displays the add to google wallet that opens the google page

This can be overriden by using data-neostore-platform="desktop" (“desktop”, “apple”, or “google” options)

Language detection

The component is looking for the user browser’s language and fallback to en either if the locale doesn’t exist for the given platform or if the user language is not supported.

You can force the language by using data-neostore-language="fr"

Customization

The general layout is:

a div of your responsibility
- a link, selector: .neostore-link
  - an image, selector .neostore-img and .neostore-link-{{ platform }} where platform is desktop, apple, android

The android and google buttons respects the google and apple design guidelines for this action. Apple guideline Google Guideline

You can still update some styles using css but remember that the link contains an image.

Advanced usage

desktop render customization

On desktop, the principal information is the url where you should redirect your users.
You can update the way you render this link to display a QR Code for example using the following snippet

<script src="https://cdn.rawgit.com/davidshimjs/qrcodejs/gh-pages/qrcode.min.js"></script>

<div id="qrcode"></div>
<script type="module">
    import { AddToWalletButton } from "https://sdk.neostore.cloud/scripts/molia/cinto@1/cinto.mjs;

    const button = new AddToWalletButton("molia", {
        passType: "user",
        passId: 'KlnqcxVLA9pS4ol5'
    });
    const url = await button.getPassPageUrl();
    new QRCode(document.getElementById("qrcode"), url);
</script>

using external identifiers with hmac

You can retrieve the passId parameters through The Wallet Crew API. It is also possible to use the externalIdentifiers and the hmac_sha256 value of the identifiers.

hmac_sha256 should be computed with one of The Wallet Crew secret.

For example, for a customerId of SC103010 and a secret of I1M8emrrJSns4Hnuibbm45eWfLQMosPGKSp1JzKsCrXeWmhjE8lZhxC2tfSRX5IJ the hmac value should be 8c5a9ebdd9b4ac8d2307cc34192f0faed441ef724c043162f0618784173d4d93

CyberChef

Exemple of hmac computing

using data-attribute

<script type="text/javascript">
(function (n, e, o) {
var s=n.createElement("script");s.src="https://sdk.neostore.cloud/scripts/"+e+"/cinto@1";s.async=1;
s.onload=function(){neostore.cinto.initialize(e,o)};n.body.appendChild(s);
})(document, "molia", { language: "fr" });
</script>

<div data-neostore-addToWalletButton
     data-neostore-passType="user"
     data-neostore-externalIdentifiers-y2.customer_Id-value="SC103010"
     data-neostore-externalIdentifiers-y2.customer_Id-hmac="cbbcfc5xxxxx"
></div>

Attributes are interpreted as lower case string by the browser. To include uppercase character prefix the character with the underscore sign : y2.customer_Id will be interpreted as y2.customerId

using component

// install cinto SDK through npm install @neostore/cinto
import { AddToWalletButton } from "@neostore/cinto";

const btn = new AddToWalletButton("molia", {
    language: "fr",
    externalIdentifiers: {
        "y2.customerId": {
            value: "SC103010",
            // hmac_sha256 of customerId with one of the neostore secret
            hmac: "cbbcfc5xxxxx",
        },
    },
});
btn.render(document.getElementById("btn"));

How to add analytics information ?

It is possible to specify 3 installation information that will be available in the Pass:Installed event used by the dashboard and the insights API.

tags : an array of string used to determine the source of this download - the utm_source and utm_campaign will automatically concatenated to the tags
medium: a string used to determine the medium of this download. It could be anything for example ecomm or mobileapp, etc.
origin: by default the url (without search parameter) of the page where the add to wallet button is used. it is possible to overrides this value

these value can be specified like this

<div data-neostore-addToWalletButton
 ....
   data-neostore-src-tags="tag1,tag2"
   data-neostore-src-medium="ecomm"
   data-neostore-src-origin="originA"
></div>

all parameters are optional

How to get passId information ?

When the pass already exists

Get an API Key on The Wallet Crew back-office :
1. https://admin.thewalletcrew.io/tenant/~/apiKeys
2. API Key should have the tenant.pass:read permission

Call the /passes API

https://app.neostore.cloud/api/{tenantId}/passes?filter=filter[0].field=y2.customerId&filter[0].operator=equals&filter[0].value=04101234

**curl -X 'GET' \ 'https://app.neostore.cloud/api/{tenantId}/passes?filter%5B0%5D.field%3Dy2.customerId%26filter%5B0%5D.operator%3Dequals%26filter%5B0%5D.value%**04101234**\ -H 'accept: text/plain' \ -H 'X-API-KEY: {apiKey}'**

Result will be something like:

[
	{
		"id": "KlnqcxVLAxxxxxx",
		"secret": "r9vuaWOxxxxxxx",
		"creationDate": "2023-07-19T11:56:34.9418747Z",
		"passType": "user",
		"identifiers": {
			"y2.customerId": "04101234"
		},
		"providers": {
			"apple": {
				"installationDate": "2023-07-19T11:56:43.2830295Z",
				"devices": [
					{
						"deviceIdentifier": "5dec2xxxxxx",
						"pushToken": "5f7f23xxxxx",
						"registrationDate": "2023-07-19T11:56:43.2830295Z"
					}
				]
			}
		}
	}
]

When the pass doesn’t exists

Third party integration

Shopify

use this liquid placeholder to display the add to wallet button :

{% assign tenantId = 'molia' %}
{% assign secret = 'sTyQrYOKtkIfT77K4wns8cUxfOTV7n57RFztd59wPNqvyvZ9sNnCy3a3s8cikz9z' %}

{% assign y2Identifier = 'SC103010' %}
{% assign y2Identifierhmac = y2Identifier | hmac_sha256: secret %}

<script type="text/javascript">
(function(n,e,o){var s=n.createElement("script");s.src="https://sdk.neostore.cloud/scripts/"+e+"/cinto";s.async=1;s.onload=function(){neostore.cinto.initialize(e, o);};n.body.appendChild(s);})
(document, {{ tenantId }});
</script>

<div
  data-neostore-addToWalletButton
  data-neostore-passType='user'
  data-neostore-externalIdentifiers='{"y2.customerId":{"value":"{{ y2Identifier }}","hmac":"{{ y2Identifierhmac }}"} }'>
</div>

React integration

It is possible to encapsulate the button within React using this component. You can adjust your component based on your needs :

import { AddToWalletButton } from "@neostore/cinto";

const CintoMobileAddToWallet = React.forwardRef<
    HTMLButtonElement,
    BoxProps & {
        passId?: string;
    }
>(({ passId, ...props }, buttonRef) => {
    const localRef = useRef<HTMLButtonElement>(null);
    buttonRef = buttonRef || localRef;

    const ctaRef = useRef<HTMLDivElement>(null);
    const cintoButtonRef = useRef<AddToWalletButton>();

    useEffect(() => {
        cintoButtonRef.current = passId
            ? new AddToWalletButton(tenantId, {
                  passId,
              })
            : undefined;
        ctaRef.current && cintoButtonRef.current?.render(ctaRef.current);
        if (passId && cintoButtonRef.current) {
            cintoButtonRef.current?.perform();
        }
    }, [passId, tenantId]);

    return (
        <Box {...props}>
            <div ref={ctaRef} />
        </Box>
    );
});

export default CintoMobileAddToWallet;