@neostore/cinto

Cinto SDK

This package allows to display a "add to wallet" button compatible with Apple & Google. It requires the usage of neostore.cloud solution.

See https://neostore.cloud for more information

Usage

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 neostore, 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: undefined
     */
    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
     * @default: undefined
     */
    passType?: 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 Neostore
• 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"

Customisation

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.

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

Case Sensitive External Identifiers

Sometimes, you need to have an uppercase in the external identifiers. Due to the HTML specication, data attribute are case insensitive. To balance this limitation, you can add an "_" before the letter you want to be uppercase.

example:

<div data-externalIdentifiers-shopify_id-value="123"></div>

Advanced customisation (desktop only)

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 "/src/index.ts";

    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 neostore API (see back-end setup). It is also possible to use the externalIdentifiers property like this :

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>

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"));

React integration

It is possible to encapsulate the button within React using this component :

import React, { useEffect, useRef } from "react";

import { Box, BoxProps } from "@mui/material";

import { useAppInsightsContext, useLayout } from "../hooks";
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;

Backend setup

See https://www.notion.so/neostore/Cinto-16b789f1a88a4d4f81975ffc9cb9c58a?pvs=4