> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/guides-enrolment/fr/inscription/on-your-website.md).

# Sur votre site web

Intégrez un bouton Ajouter à Wallet sur le site web d'une marque avec le SDK cinto de The Wallet Crew, incluant la détection Apple/Google et une solution de secours sur ordinateur.

**cinto** est le SDK JavaScript de The Wallet Crew pour intégrer des boutons Add to Wallet sur n'importe quelle page web. Le SDK détecte l'appareil et affiche automatiquement le bon appel à l'action.

Sur iOS, il affiche **Add to Apple Wallet**. Sur Android, il affiche **Add to Google Wallet**. Sur ordinateur, il peut rediriger vers une [page de téléchargement](https://docs.thewalletcrew.io/guides-enrolment/fr/inscription/download-pages.md) ou prendre en charge une solution de repli basée sur un QR code.

<details>

<summary><strong>Exemples concrets</strong></summary>

* Une page de compte de fidélité affiche un bouton pour la carte du client connecté.
* Une section de cartes cadeaux affiche un bouton par carte cadeau active.
* Une page de billetterie affiche un bouton par billet, et non un bouton par commande.

</details>

<figure><img src="https://831874859-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlFokgwgJiwLXu7G8MVSJ%2Fuploads%2FQnCNBcX4i6sfADfIDZgy%2Fillustration-add-to-wallet-sdk-integration.png?alt=media&#x26;token=8f676cd5-9bcb-47e7-ac27-53614518f730" alt="Add to Wallet button embedded on a website with device-specific rendering."><figcaption><p>La même intégration adapte le bouton à iOS, Android et aux ordinateurs de bureau.</p></figcaption></figure>

## Fonctionnement de l'intégration sur le site web

L'intégration est simple. Une page charge le SDK cinto, puis affiche un bouton qui récupère une carte.

Cette carte peut être résolue de deux façons :

* avec un `passId`
* avec `externalIdentifiers` et un HMAC facultatif

### Chaque carte doit être unique

Ce point est crucial. Une carte Wallet est **pas** une ressource partagée.

Chaque carte doit représenter un client, une carte, un billet ou une instance de droit d'accès. Le bouton affiché sur une page doit résoudre uniquement la carte qui appartient au contexte actuel.

Par exemple :

* une page de carte de fidélité doit résoudre la carte du client actuel
* une liste de billets doit résoudre une carte distincte par billet
* une liste de cartes cadeaux doit résoudre une carte distincte par carte cadeau

{% hint style="warning" %}
Ne réutilisez jamais la même valeur d'identifiant statique pour chaque client. Si le même `customerId`, l'identifiant du billet ou la valeur de recherche de carte est codée en dur pour tous les visiteurs, la même carte peut être renvoyée à tout le monde.
{% endhint %}

Lorsque `externalIdentifiers` sont utilisés, la valeur de l'identifiant doit être suffisamment unique pour résoudre **exactement une carte**. Si une recherche renvoie plusieurs cartes, la stratégie d'identifiant n'est pas assez spécifique pour une distribution sur le site web.

### Ce qui change selon l'appareil

Le SDK affiche automatiquement le comportement correct :

* **iOS :** télécharge la carte Apple Wallet
* **Android :** ouvre le processus d'enregistrement dans Google Wallet
* **Ordinateur :** redirige vers une page de téléchargement

Ce comportement par défaut peut être remplacé si nécessaire : définissez `data-neostore-platform="desktop"` (ou `apple`, `google`) ou utilisez l' `platform` option dans le composant.

#### Exemple de rendu

**iOS**

<figure><img src="https://831874859-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlFokgwgJiwLXu7G8MVSJ%2Fuploads%2F7BgqaHarZQ0jXz0tlQ8k%2Fenroll-website-ios-mobile-device.png?alt=media&#x26;token=6bc7b7c8-532a-4865-9ecc-e2a723e75aec" alt="Add to Apple Wallet button shown on iPhone." width="250"><figcaption></figcaption></figure>

**Android**

<figure><img src="https://831874859-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlFokgwgJiwLXu7G8MVSJ%2Fuploads%2Fc5UFGREPwkZ2pYKfhidd%2Fenroll-website-android-mobile-device.png?alt=media&#x26;token=d34e7b68-dd15-4054-8b99-69039334a494" alt="Add to Google Wallet button shown on Android." width="250"><figcaption></figcaption></figure>

**Ordinateur**

<figure><img src="https://831874859-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlFokgwgJiwLXu7G8MVSJ%2Fuploads%2FvpVCqxoxVNTk6kbijj5C%2Fenroll-website-otherwise.png?alt=media&#x26;token=c7a33eb9-96c2-417f-9fb6-97f13584bdaa" alt="Desktop fallback rendering for Add to Wallet." width="250"><figcaption></figcaption></figure>

La solution de repli sur ordinateur ouvre une page de téléchargement comme :

<figure><img src="https://831874859-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlFokgwgJiwLXu7G8MVSJ%2Fuploads%2F2XHK45WZLt2FhuIHebvw%2Fenroll-website-ui-result.png?alt=media&#x26;token=8efaa7d7-c727-4b2c-b107-e466a35accc5" alt="Download page used as desktop fallback for website distribution."><figcaption><p>Vérifiez que la page de téléchargement résout la carte attendue pour le contexte actuel.</p></figcaption></figure>

## Choisissez comment le bouton résout la carte

Le principal choix d'implémentation est la méthode de résolution de la carte.

Utilisez `passId` lorsque le backend connaît déjà la carte exacte. Utilisez `externalIdentifiers` lorsque le site web a accès à un identifiant métier stable et que la carte doit être résolue dynamiquement.

### Commencez par `tenantId` et `environment`

Deux valeurs du SDK sont particulièrement importantes :

* `tenantId`
* `environment`

`tenantId` est requis. Il s'agit du nom du locataire dans le système The Wallet Crew. Dans les exemples de cette page, `acme` est le `tenantId`; remplacez-le par le vrai nom du locataire.

`environment` est l'URL de base publique utilisée par le SDK.

Utilisez ces valeurs comme suit :

* **Production :** `https://<customDomain>` ou l'URL générique `https://app.thewalletcrew.io` lorsqu'aucun domaine personnalisé n'est configuré
* **Test / QA :** `https://app-qa.thewalletcrew.io`

Le préfixe `neostore` est l'ancien nom de la plateforme et est conservé dans les identifiants techniques. Le package `@neostore/cinto`, la variable globale `neostore.cinto` et les `data-neostore-*` attributs sont les vrais noms utilisés par le SDK.

### Option 1 — Résoudre avec `passId`

C'est l'option la plus simple. Elle fonctionne le mieux lorsque le backend connaît déjà la carte exacte à afficher.

{% tabs %}
{% tab title="JavaScript natif" %}

```html
<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, "acme", {});
</script>

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

{% endtab %}

{% tab title="module npm" %}

```bash
npm install @neostore/cinto
```

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

const btn = new AddToWalletButton("acme", {
    language: "fr",
    passId: "<passId>",
});

btn.render(document.getElementById("btn"));
```

{% endtab %}
{% endtabs %}

### Option 2 — Résoudre avec `externalIdentifiers`

Cette option est utile lorsque la page connaît un identifiant métier stable, par exemple un identifiant de fidélité, un identifiant CRM ou un identifiant de billet, mais ne connaît pas `passId` encore.

L'identifiant doit appartenir au client ou à l'objet actuel. Il ne doit pas s'agir d'une constante partagée.

Lorsque HMAC est utilisé, calculez la signature côté serveur avec le secret du locataire, comme décrit dans [Pages de téléchargement](https://docs.thewalletcrew.io/guides-enrolment/fr/inscription/download-pages.md#build-a-delivery-url). Dans les extraits ci-dessous, `cbbcfc5xxxxx` est un espace réservé tronqué pour la valeur HMAC.

Par exemple, pour un `customerId` de `SC103010` et un secret d'exemple de `ExampleSecretOnlyForThisDocNeverUseItInProduction0123456789abcd`, la valeur HMAC est :

`f1ac83b1055fb7d57c4dbf213037d3de3bad2dd5744b5a6580d7ab1ea5a0855e`

Outil de référence : [CyberChef](https://gchq.github.io/CyberChef/#recipe=HMAC\({'option':'UTF8','string':'ExampleSecretOnlyForThisDocNeverUseItInProduction0123456789abcd'},'SHA256'\)\&input=U0MxMDMwMTA)

{% hint style="warning" %}
Le secret HMAC doit rester côté serveur. Il ne doit jamais être exposé dans le code du navigateur.
{% endhint %}

#### Attributs de données

```html
<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, "acme", { 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>
```

#### Utilisation du composant

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

const btn = new AddToWalletButton("acme", {
    language: "fr",
    passType: "user",
    externalIdentifiers: {
        "y2.customerId": {
            value: "SC103010",
            hmac: "cbbcfc5xxxxx",
        },
    },
});

btn.render(document.getElementById("btn"));
```

#### Casse des clés d'identifiant en HTML

Les navigateurs mettent les noms d'attributs HTML en minuscules. Pour conserver une majuscule dans une clé d'identifiant, préfixez le caractère avec `_` dans le nom de l'attribut.

Exemple :

* `y2.customer_Id` devient `y2.customerId`

Cette règle affecte uniquement le nom de l'attribut HTML. Elle ne modifie pas la valeur signée.

## Comportement et options courants

### Détection de la langue

Le SDK utilise la langue du navigateur par défaut. Si la locale n'est pas disponible, il revient à l'anglais.

Pour forcer une langue :

* attributs de données : `data-neostore-language="fr"`
* option du composant : `language: "fr"`

### Options complètes

Voici la liste de toutes les options disponibles.

```typescript
export interface Options {
    /**
     * URL de base publique de l'environnement.
     * Utilisez "https://app-qa.thewalletcrew.io" pour les tests.
     * Utilisez "https://app.thewalletcrew.io" pour la production.
     * Un domaine personnalisé du locataire peut également être utilisé.
     * @default: "https://app.thewalletcrew.io"
     */
    environment?: string;
    /**
     * Nom du locataire dans le système The Wallet Crew.
     * Cette valeur est requise.
     * Exemple : "acme"
     */
    tenantId: string;
    /**
     * Nom de la mise en page de carte vers laquelle rediriger l'utilisateur lorsqu'il est sur ordinateur
     * @default: undefined // la mise en page de carte par défaut du modèle de carte sera utilisée
     */
    passLayoutName?: string;
    /**
     * Code langue ISO 639 à utiliser pour afficher le bouton. Lorsqu'il est omis, la langue sera détectée automatiquement en fonction des paramètres du navigateur.
     * Si la valeur ne correspond à aucune option disponible, les paramètres du navigateur seront utilisés ; sinon, l'anglais sera utilisé.
     * @default: undefined
     */
    language?: string;
    /**
     * Identifiant de la carte à afficher, ou promesse de celui-ci
     */
    passId: string | (() => Promise<string>);
    /**
     * Plateforme à utiliser pour afficher le bouton. Lorsqu'elle est omise, la plateforme sera détectée automatiquement en fonction de l'agent utilisateur.
     * Les valeurs possibles sont : "apple", "google" ou "desktop"
     *
     * @default: undefined
     **/
    platform?: Platform;
    /**
     * Identifiants externes à utiliser pour obtenir le passId
     */
    externalIdentifiers?: Record<string, { value: string; hmac?: string }>;
    /**
     * Type de carte à utiliser pour obtenir le passId
     * Requis lorsque externalIdentifiers est défini
     */
    passType?: string;
    
    /**
     * Source utilisée à des fins d'analyse
     */
    source?: {
        /**
         * liste des tags à associer à ce téléchargement. utm_source et utm_campaign seront automatiquement ajoutés à cette liste
         */
        tags?: Array<string>;
        /**
         * support à associer à ce téléchargement. utm_medium sera utilisé si aucune valeur n'est spécifiée
         */
        medium?: string;
        /**
         * origine à associer à ce téléchargement. l'URL actuelle (sans la requête) sera utilisée si aucune valeur n'est spécifiée
         */
        origin?: string;
    };

    /**
     * Fonction de rappel appelée lorsque le bouton est cliqué
     */
    onClick?: (e: MouseEvent, data: { options: Partial<Options>; platform: Platform }) => void;

    /**
     * Fonction de rappel lorsqu'une erreur se produit
     *
     */
    onError?: (error: string) => void;
}

```

### Mise en forme

La structure rendue est :

* un conteneur fourni par le site web
  * un lien avec sélecteur `.neostore-link`
    * une image avec des sélecteurs `.neostore-img` et `.neostore-link-{{ platform }}`

Sur mobile, le bouton doit suivre les directives de conception d’Apple et de Google. L’élément de marque, le libellé, l’espacement et la présentation générale doivent rester conformes aux exigences de chaque fournisseur.

Les éléments de bouton Apple et Google respectent les consignes de chaque fournisseur :

* [Consigne Apple](https://developer.apple.com/wallet/add-to-apple-wallet-guidelines/)
* [Consigne Google](https://developers.google.com/wallet/generic/resources/brand-guidelines)

## Personnalisation du bureau

Sur ordinateur, la sortie la plus importante est l’URL de la page de téléchargement. Cette URL peut être utilisée pour afficher un code QR à la place du bouton de redirection par défaut.

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/qrcodejs/1.0.0/qrcode.min.js"></script>

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

    const button = new AddToWalletButton("acme", {
        passId: "<passId>"
    });

    const url = await button.getPassPageUrl();
    new QRCode(document.getElementById("qrcode"), url);
</script>
```

## Ajouter des informations d'analyse

Le bouton peut envoyer trois valeurs source qui seront visibles dans le `Carte:Installé` l'événement, le tableau de bord et l'API Insights. Ils utilisent le même `balises|medium|origin` source que le `neo.src` paramètre décrit dans [Pages de téléchargement](https://docs.thewalletcrew.io/guides-enrolment/fr/inscription/download-pages.md#add-campaign-tracking).

* `balises`: liste de balises source. `utm_source` et `utm_campaign` sont ajoutés automatiquement.
* `média`: libellé de canal tel que `ecomm` ou `compte`.
* `origine`: URL de la page source. Par défaut, l'URL de la page actuelle est utilisée sans paramètres de requête.

Toutes les valeurs sont facultatives.

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

## Récupérer `passId` lorsque la Carte existe déjà

Lorsque la Carte existe déjà, le backend du site la recherche d'abord avec une clé API qui a `tenant.Carte:lecture`, comme décrit dans [Trouver la Carte du client](https://docs.thewalletcrew.io/guides-enrolment/fr/inscription/on-your-mobile-app.md#find-the-customers-pass). La recherche doit renvoyer une Carte : zéro signifie que la Carte n'existe pas encore, et plusieurs signifie que l'identifiant n'est pas suffisamment unique pour la distribution sur le site web. Utilisez la `id` comme `passId` dans le bouton du site web.

## Exemple d'intégration tierce

<details>

<summary><strong>Exemple de wrapper React</strong></summary>

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

// tenantId est le nom du locataire, par exemple "acme"
const tenantId = "acme";

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

`perform()` déclenche la même action qu'un clic sur le bouton. Les navigateurs peuvent bloquer les fenêtres contextuelles et les téléchargements, sauf si elle est appelée à partir d'un geste de l'utilisateur.

</details>

## FAQ

<details>

<summary><strong>Peut-on afficher plusieurs boutons sur la même page ?</strong></summary>

Oui. C'est courant pour les listes de billets et les listes de cartes-cadeaux. Chargez le SDK une seule fois, puis affichez un bouton par Carte.

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/guides-enrolment/fr/inscription/on-your-website.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
