Dépannage

Problèmes courants avec l'intégration v4 et corrections rapides.

1) Le widget n'apparaît pas

Vérifiez les deux attributs obligatoires du script:

<script src="https://widget-app.zykay.com/v4/loader.min.js"
        data-partner-id="pk_live_xxx"
        data-success-path="/verified"></script>

Causes fréquentes:

• data-success-path absent
• data-partner-id invalide
• blocage CSP de widget-app.zykay.com

2) Erreur Missing required data attributes

Le loader logue cette erreur si data-partner-id ou data-success-path est manquant.

[ZYKAY v4] Missing required data attributes: data-partner-id, data-success-path

3) Vérification réussie mais grant non traité

Le grant_code arrive dans le fragment URL, pas dans la query string.

const hash = new URLSearchParams(window.location.hash.slice(1));
const grantCode = hash.get('grant_code');

4) INVALID_SIGNATURE sur /v1/exchange

Checklist:

1. Secret décodé en base64 avant HMAC
2. timestamp en secondes (pas millisecondes)
3. Chaîne canonique exacte: bodyHash.timestamp.partnerId.nonce
4. Body JSON compact exact signé et envoyé

5) Mobile: l'app ne s'ouvre pas

• Vérifiez que vous utilisez le loader v4 officiel
• Vérifiez que le téléphone a l'app ZYKAY installée
• Testez sans bloqueur de contenu
• Ouvrez la console distante Safari/Chrome pour confirmer le click handler

6) Polling bloqué en pending

Vérifiez:

• connectivité vers GET /api/w/verify-status/:requestId?pt=...
• expiration de la session (TTL dépassé)
• cohérence entre request_id et poll_token

7) Portefeuille EUDI : le widget ne passe pas en mode EUDI

Vérifiez que l'attribut est exactement data-client-proof-mode="true" (pas "1", "yes", ou true sans guillemets) :

<script src="https://widget-app.zykay.com/v4/loader.min.js"
        data-partner-id="pk_live_xxx"
        data-success-path="/verified"
        data-scopes="isAdult,isFrench"
        data-client-proof-mode="true"
        data-debug="true"></script>

Activez data-debug="true" et vérifiez dans la console que le mode est bien détecté.

8) Portefeuille EUDI : l'app ne s'ouvre pas sur iPhone

• Vérifiez que l'application ZYKAY est installée sur le téléphone
• Les Universal Links ne fonctionnent pas dans les navigateurs in-app (Instagram, Facebook, TikTok) — testez dans Safari ou Chrome natif
• Vérifiez que le QR code pointe vers https://app.zykay.com/verify?request_id=...

9) Portefeuille EUDI : erreur de scope non supporté

Les scopes isMale, isFemale, revealNationality et revealBirthYear ne sont pas disponibles avec le Portefeuille EUDI. Retirez-les de data-scopes lorsque data-client-proof-mode="true" est actif.

10) Portefeuille EUDI : temps de vérification long

Si la première visite dépasse systématiquement 30 secondes, vérifiez la connectivité réseau du téléphone. Pour les détails des parcours, consultez Parcours Portefeuille EUDI.

11) Debug conseillé

Activez:

<script src="https://widget-app.zykay.com/v4/loader.min.js"
        data-partner-id="pk_live_xxx"
        data-success-path="/verified"
        data-debug="true"></script>