# SDK de parrainage pour site sur mesure

# Ajouter Frak à un site personnalisé

Pour un site personnalisé, l'ajout de Frak se résume à charger un script, configurer un objet de configuration et intégrer les composants de votre choix. Choisissez ci-dessous la configuration qui correspond à votre technologie.

**Avant de commencer:** Commencez par enregistrer votre site et ajouter votre domaine dans le [tableau de bord professionnel](https://business.frak.id/). Votre identifiant marchand est alors automatiquement récupéré à partir de votre domaine, ce qui permet de garder une configuration très courte. Voir [Enregistrer votre site](/fr/guides/dashboard/register/).

**Les récompenses nécessitent une confirmation de votre serveur:** Le suivi sur la page indique à Frak qu'une commande est en cours. Les récompenses ne sont envoyées qu'une fois que votre serveur confirme la vente avec un webhook signé. Voir [Valider les achats depuis votre backend](/fr/guides/platforms/custom/backend/).

## Les composants

Ces trois composants sont des [composants web](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) universels. Ils fonctionnent de la même manière, que vous écriviez du simple code HTML, utilisiez un bundler ou développiez avec React.

| Composant | Emplacement | Rôle |
| --- | --- | --- |
| `<frak-button-share>` | Page produit, page d'accueil | Permet aux clients de partager votre boutique et de gagner des récompenses |
| `<frak-banner>` | Haut de la page | Accueille les visiteurs parrainés |
| `<frak-post-purchase>` | Page de confirmation de commande | Propose le partage juste après le paiement et suit la commande |

<Aside type="caution" title="Les noms d'attributs s'écrivent avec des tirets">
En HTML et JSX, les attributs composés de plusieurs mots doivent s'écrire avec des tirets et non en camelCase : utilisez `customer-id`, pas `customerId`. Les navigateurs convertissent les noms d'attributs en minuscules, un attribut en camelCase serait donc ignoré sans avertissement.
</Aside>

## Ajouter Frak à votre site

### Charger et configurer Frak

Ajoutez ceci dans la balise `<head>` de vos pages. L'objet de configuration est lu par Frak lors de son chargement, configurez-le donc **avant** la balise script.

```html title="index.html"
<head>
  <!-- 1. Configure Frak (domain defaults to the current host) -->
  <script>
    window.FrakSetup = {
      config: {
        metadata: {
          name: "Your Store",
          currency: "eur",
        },
      },
    };
  </script>

  <!-- 2. Avoid a flash of unstyled elements while the script loads -->
  <style>
    frak-button-share:not(:defined),
    frak-banner:not(:defined),
    frak-post-purchase:not(:defined) { display: none !important; }
  </style>

  <!-- 3. Load the components (auto-registers them and boots the SDK) -->
  <link rel="dns-prefetch" href="https://sdk.frak.id">
  <link rel="preconnect" href="https://sdk.frak.id">
  <link rel="dns-prefetch" href="https://cdn.jsdelivr.net">
  <link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin>
  <script
    src="https://sdk.frak.id/components.js"
    defer="defer"
    onerror="var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/@frak-labs/components@latest/cdn/components.js';s.defer=true;document.head.appendChild(s)"
  ></script>
</head>
```

`sdk.frak.id` est le pointeur CDN maison de Frak : une publication vous atteint en quelques minutes, et `onerror` bascule vers jsDelivr s'il est injoignable. Voir le [guide d'intégration CDN / navigateur](/developers/integration/cdn/) (en anglais) pour le détail du fallback et des preconnects.

### Ajouter les composants

Placez la bannière en haut de votre `<body>`, et le bouton de partage là où vous souhaitez que vos clients partagent :

```html
<body>
  <!-- Welcomes referred visitors -->
  <frak-banner></frak-banner>

  <!-- Inherits your theme's .button styles via classname -->
  <frak-button-share classname="button"></frak-button-share>
</body>
```

### Suivre l'achat

Sur votre page de confirmation de commande, ajoutez la carte post-achat avec les détails de la commande. Lorsque `customer-id`, `order-id` et `token` sont tous présents, la carte enregistre également la commande automatiquement auprès de Frak :

```html
<frak-post-purchase
  customer-id="cust_123"
  order-id="order_456"
  token="a-unique-order-token"
></frak-post-purchase>
```

Si vous ne souhaitez pas afficher la carte, vous pouvez enregistrer la commande directement à la place. L'action devient disponible dès que Frak est prêt :

```html
<script>
  window.addEventListener("frak:client", () => {
    window.FrakSetup.core.trackPurchaseStatus({
      customerId: "cust_123",
      orderId: "order_456",
      token: "a-unique-order-token",
    });
  });
</script>
```

### Installation

```bash
npm install @frak-labs/components @frak-labs/core-sdk
```

### Configurer Frak

Définissez la configuration dans son propre module afin qu'elle s'exécute en premier :

```ts title="frak-setup.ts"
import type { FrakWalletSdkConfig } from "@frak-labs/core-sdk";

declare global {
  interface Window {
    FrakSetup: { config?: FrakWalletSdkConfig };
  }
}

window.FrakSetup = {
  config: {
    metadata: {
      name: "Your Store",
      currency: "eur",
    },
  },
};
```

### Enregistrer les composants

Importez d'abord votre module de configuration, puis importez chaque composant que vous utilisez. L'importation d'un composant enregistre son élément personnalisé et démarre le SDK à partir de `window.FrakSetup.config` :

```ts title="main.ts"
import "./frak-setup";
import "@frak-labs/components/banner";
import "@frak-labs/components/buttonShare";
import "@frak-labs/components/postPurchase";
```

Ensuite, insérez les éléments dans votre code, exactement comme dans l'onglet HTML :

```html
<frak-banner></frak-banner>
<frak-button-share classname="button"></frak-button-share>
<frak-post-purchase
  customer-id="cust_123"
  order-id="order_456"
  token="a-unique-order-token"
></frak-post-purchase>
```

### Suivre l'achat

La carte post-achat suit automatiquement la commande lorsqu'elle reçoit ces trois attributs. Pour effectuer le suivi sans afficher la carte, appelez directement l'action :

```ts
import { trackPurchaseStatus } from "@frak-labs/core-sdk/actions";

await trackPurchaseStatus({
  customerId: "cust_123",
  orderId: "order_456",
  token: "a-unique-order-token",
});
```

Les composants visuels sont les mêmes composants web, utilisés dans JSX. Installez-les ainsi que (facultativement) `@frak-labs/core-sdk` pour les appels directs d'actions :

```bash
npm install @frak-labs/components @frak-labs/core-sdk
```

### Configurer et enregistrer

Définissez la configuration dans son propre module, puis importez-le (ainsi que les composants) avant d'afficher votre application :

```ts title="frak-setup.ts"
import type { FrakWalletSdkConfig } from "@frak-labs/core-sdk";

declare global {
  interface Window {
    FrakSetup: { config?: FrakWalletSdkConfig };
  }
}

window.FrakSetup = {
  config: {
    metadata: {
      name: "Your Store",
      currency: "eur",
    },
  },
};
```

```tsx title="main.tsx"
import "./frak-setup";
import "@frak-labs/components/banner";
import "@frak-labs/components/buttonShare";
import "@frak-labs/components/postPurchase";

import { createRoot } from "react-dom/client";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(<App />);
```

### Utiliser les composants dans JSX

```tsx title="App.tsx"
export function App() {
  return (
    <>
      <frak-banner />
      <frak-button-share classname="button" />

      {/* On your order confirmation route */}
      <frak-post-purchase
        customer-id="cust_123"
        order-id="order_456"
        token="a-unique-order-token"
      />
    </>
  );
}
```

La carte post-achat suit automatiquement la commande. Pour suivre la commande sans la carte, appelez `trackPurchaseStatus` depuis `@frak-labs/core-sdk/actions` une fois la commande validée.

**TypeScript:** Il est possible que TypeScript ne reconnaisse pas les balises `<frak-*>` dans le JSX. Ajoutez une petite déclaration pour y remédier :

```ts title="frak.d.ts"
import type { HTMLAttributes } from "react";

declare global {
  namespace JSX {
    interface IntrinsicElements {
      "frak-banner": HTMLAttributes<HTMLElement>;
      "frak-button-share": HTMLAttributes<HTMLElement> & { classname?: string; text?: string };
      "frak-post-purchase": HTMLAttributes<HTMLElement> & {
        "customer-id"?: string;
        "order-id"?: string;
        token?: string;
      };
    }
  }
}
```

Avec React 19, déclarez le même `namespace JSX` à l'intérieur de `declare module "react"` au lieu de `declare global`.

<Aside type="note" title="Besoin d'un contrôle programmatique ?">
Pour les parcours personnalisés (statut du portefeuille, hooks de parrainage, ouverture manuelle de la modale), `@frak-labs/react-sdk` fournit des hooks et des providers React. Voir le [guide d'intégration React](/developers/integration/react/).
</Aside>

**Toutes les options:** La liste complète des attributs pour chaque composant est disponible dans la référence développeur : [bouton de partage](/developers/components/share-button/), [bannière](/developers/components/banner/), [post-achat](/developers/components/post-purchase/) et la [configuration `FrakSetup`](/developers/components/frak-setup/).

## Étapes suivantes

[Validation backend](/fr/guides/platforms/custom/backend/)
  [Applications mobiles](/fr/guides/platforms/custom/mobile/)
  [Référence des composants](/developers/components/)
  [Guide Vanilla JS / CDN](/developers/integration/cdn/)