Identification externe des utilisateurs ​

Cette fonctionnalité permet d'identifier les utilisateurs arrivant sur le jeu concours depuis un service externe. Cela peut servir plusieurs besoins :

• Controle d'accès externe
• Controle d'accès fonctionnel (donner une participation au jeu concours à un client ayant fait une commande)
• Intégration fluide du jeu concours sur votre site pour les clients

Afin d'assurer le fonctionnement de cette interaction, vous devez développer un service accessible via une url publique qui sera capable de fournir des informations sur un utilisateur de votre site à partir d'un token que vous nous aurez fourni.

Afin de bien démarrer, lisez attentivement la partie conseils

Paramétrage ​

Dans l'éditeur de votre jeu concours, allez dans Paramères > Identification externe Cet onglet est accessible sur les offres ayant l’option dédiée activée.

Dans cet onglet, un paramètre permet d’activer l’option identification externe. Un second paramètre permet de forcer l’utilisation du token. Dans ce cas, si le jeu est appelé sans token ou avec un token non valide (pour lequel l’api ne fournit pas les données), une page d’erreur sera affichée lors d'une tentative d'accès au jeu concours.

Le paramètre suivant est l’url du serveur à appeler. Cette url sera appelée depuis nos serveurs et seuls les appels depuis le domaine api.clickncom.com peuvent être filtrés. Cette url sera appelée en POST et il est recommandé d’avoir une url avec un certificat ssl (https)

Ensuite viennent les paramètres attendus. Les données attendues par clickncom sont les données du formulaire.

La page de paramétrage montre la liste des paramètres attendus en retour (un objet json avec une clé pour chaque entrée de formulaire, les clés attendues sont explicitées pour chaque paramètre.) Le clés obligatoires sont mentionnées. Une clé est appelée Critère de regroupement, c’est la clé permettant de regrouper les participants étant les même personnes. Typiquement, par défaut, clickncom utilise l’adresse email, mais dans le cadre du SSO, un identifiant utilisateur interne au système externe semble tout aussi pertinent.

Clickncom s’adapte à tous les systèmes externes puisque le formulaire peut être paramétré avec les données souhaitées. Si la clé de regroupement est un identifiant interne du système externe, il est possible de le paramétrer.

Pour chaque élément, vous pouvez indiquer :

• si le champ est éditable ou non dans le formulaire si ce champ est pré rempli. Si le système externe a fourni sa valeur, le participant ne pourra pas éditer ce champ.
• si le champ est visible ou non dans le formulaire si ce champ est pré rempli. Si le champ doit être caché au participant et que le système externe a fourni sa valeur, le participant ne verra pas ce champ.

Le système externe peut fournir d’autres informations ne correspondant pas à des champs de formulaire. Celles-ci seront stockées sur la participation et pourront être récupérées via les webhooks.

Un bouton de test permet de saisir un token et de valider que la réponse du serveur est conforme.

Attention au temps de réponse de votre service, si votre service est lent, l'accès au jeu concours sera ralenti pour les participants.

Conseils ​

Quel que soit l'implémentation de votre service, vous devrez fournir un token via l'url du jeu concours qui permettra d'identifier le participant.

Nous vous recommandons de fournir des tokens uniques générés à la demande. La réutilisation d’un token pourrait poser des problèmes de sécurité. Ce token étant présent dans l’url du jeu fournie à l’utilisateur, il pourrait être partagé, ou réutilisé, ce qui entrainerait des participations multiples (ce qui cependant peut être souhaité dans certains cas).

N’importe qui en possession du token peut jouer à la place de l’utilisateur, clickncom recommande donc de piloter l’accès au jeu :

• Lorsque l’utilisateur a le droit de participer au jeu (selon les règles établies par le système externe), un token unique est généré et stocké
• Lorsque le participant souhaite jouer, l’url contenant le token lui est proposée (iframe, lien, …)
• Lorsque le participant valide le formulaire (après avoir accepté le règlement par exemple), clickncom peut appeler un système externe via un webhook (autre paramétrage). Dans ce cas, le système externe est appelé avec les données du formulaire (dont le token), le système externe peut invalider ce token.

Paramétrage du rejeu : il est possible de piloter le rejeu de plusieurs façons :

• Paramétrage du rejeu coté clickncom (nombre de fois, fréquence, …). Dans ce cas, le système externe renvoie la même clé de regroupement (adresse email, identifiant client, …) pour tous les appels des tokens d’un même client et on est dans le fonctionnement classique de clickncom, le système externe pilote toujours la distribution des tokens. Il peut être plus simple dans certains cas de générer les tokens à la demande sans contrôler leur nombre et laisser clickncom s’occuper du rejeu
• Paramétrage du rejeu coté système externe : les tokens sont délivrés dans les cas de rejeu souhaité. Dans ce cas, le paramétrage clickncom doit autoriser à rejouer un nombre illimité de fois. C’est l’appel au système externe qui contrôlera que la participation doit se faire.

La synergie de cette interaction entre clickncom et le système externe dans le cas d’un rejeu doit entraîner une attention particulière au paramétrage effectué pour éviter de tomber dans des cas de refus de participation non souhaités.

Implémentation du service ​

Le serveur externe doit écouter les requêtes POST sur une route dédiée

Il va recevoir des appels avec un body contenant :

{
  "token": "token_fourni",
  "fields": ["field1", "field2"], // Ex : ["email", "firstname", "name"],
  "mandatory": ["field1"] // Ex : ["email"]
}

Les paramètres sont les suivants :

• token contient le token fourni par l'appelant via l'url du jeu (paramètre query t), exemple https://cncplay.com/p/slug_jeu_concours?t=TOKEN
• fields contient un tableau d'attributs attendus en retour, ce sont les identifiants des champs de formulaire éditables (les cases à cocher ne peuvent pas être pré remplies)
• mandatory contient un tableau d'attributs (sous tableau de fields) dont les valeurs sont obligatoires en retour. Clickncom attends ces valeurs pour fonctionner correctement.

Il doit retourner :

{
  "status": "ok",
  "data": {
    "field1": "value1", // Ex : "email" : "a@domain.com"
    "field2": "value2" // Ex : "name" : "Dupont"
  }
}

Tout status différent de 'ok' générera une erreur et entraînera la non participation au jeu. Les données retournées par le serveur seront stockées sur la participation

Les données dans data (field1, field2) sont les données de formulaire et dépendent donc du paramétrage du jeu concours. Les données attendues sont décrites sur la page de paramétrage dédiée dans l’éditeur du jeu.

De façon assez générale, les champs de formulaire ont un nom lié à leur type. Par défaut, pour un jeu auquel aucune modification n’a été apportée, les champs attendus sont { name, firstname, email }

Exemple d'implémentation du service ​

Le module ci dessous est un module NodeJS basé sur Express

module.exports = function (app, io) {
  app.post("/identification", function (req, res) {
    let token = req.body?.token,
      fields = req.body?.fields || [],
      mandatory = req.body?.mandatory || [];

    if (token) {
        let user = await getUserByToken(token) // à implémenter selon votre logique métier
        if (user) {
            let data = { ext_id: user.id } // exemple de donnée externe passée à clickncom

            fields.forEach((f) => {
                if (f.indexOf("email") === 0) {
                    data[f] = user.email;
                } else if (f.indexOf("name") === 0) {
                    data[f] = user.lastname;
                } else if (f.indexOf("fullname") === 0) {
                    data[f] = user.lastname + " " + user.firstname;
                } else if (f.indexOf("firstname") === 0) {
                    data[f] = user.firstname;
                } else if (f.indexOf("phone") === 0) {
                    data[f] = user.phone;
                }
                // ... autres champs
            });
            res.json({
                status: "ok",
                data,
            });
        } else {
            res.json({
                status: "unknown",
            });
        }
    } else {
      res.json({
        status: "no_token",
      });
    }
  });
};