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

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.

Les composants

Ces trois composants sont des composants web 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

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.

Ajouter Frak à votre site

HTML / Vanilla JS

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.

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 (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 :

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

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

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

npm / bundler

Installation

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 :

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 :

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 :

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

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

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

React

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 :

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 :

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",
    },
  },
};

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

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 :

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.

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.

Toutes les options

La liste complète des attributs pour chaque composant est disponible dans la référence développeur : bouton de partage, bannière, post-achat et la configuration FrakSetup.

Étapes suivantes

Validation backendConfirmez les vraies commandes à l'aide d'un webhook signé, afin que les récompenses ne soient déclenchées que sur de véritables ventes.

Applications mobilesAjoutez Frak à vos applications natives Android et iOS.

Référence des composantsDécouvrez tous les attributs disponibles pour chaque composant Frak.

Guide Vanilla JS / CDNUn guide plus détaillé sur l'installation via la balise script.