Comment configurer le postback pour l'offre murale de CPAlead.com : Un guide simple

Auteur: CPAlead

Mis à jour Friday, September 20, 2024 at 8:34 AM CDT

Comment configurer le postback pour l'offre murale de CPAlead.com : Un guide simple

La configuration d’un postback est la méthode la plus fiable pour récompenser automatiquement les utilisateurs lorsqu’ils complètent des offres dans votre CPAlead Offerwall. Au lieu de vérifier les conversions manuellement, CPAlead envoie une requête serveur à serveur à votre endpoint chaque fois qu’un lead éligible est créé.

La configuration la plus sûre est simple : transmettez votre propre référence utilisateur ou transaction dans {subid}, stockez {lead_id} afin que les nouvelles tentatives ne créditent pas deux fois la même conversion, et récompensez à partir de {payout}. Dans la plupart des cas, c’est tout ce dont vous avez besoin pour lancer.

Ce que fait réellement un postback éditeur

Lorsqu’un utilisateur clique sur votre URL de suivi CPAlead et complète une offre, CPAlead peut appeler votre serveur avec les données de conversion. Cela permet à votre application, site web ou jeu de récompenser automatiquement l’utilisateur sans qu’aucune personne n’ait à examiner les conversions manuellement.

Récompensez automatiquement les utilisateurs : créditez des points, du solde, des pièces ou un accès premium dès qu’une conversion est enregistrée.
Conservez votre propre registre : stockez chaque conversion dans votre propre base de données pour la finance, le support et l’analytique.
Évitez les récompenses en double : utilisez l’unique {lead_id} de CPAlead pour ignorer les nouvelles tentatives en toute sécurité.
Suivez un contexte plus riche : incluez des valeurs optionnelles comme le pays, l’IP, les identifiants d’appareil ou des subid supplémentaires si votre workflow en a besoin.

Étape 1 : transmettez votre propre référence dans l’URL de l’Offerwall

Avant de vous soucier de l’URL du postback, assurez-vous que l’URL de suivi CPAlead d’origine contient votre propre identifiant dans subid. Il peut s’agir d’un ID utilisateur, d’un nom d’utilisateur, d’un wallet ID, d’une clé de session ou de toute référence interne que vous utilisez pour savoir quel utilisateur doit être récompensé.

https://your-tracking-domain/view.php?id=1234&pub=1234&subid=USER_123

Si vous avez besoin d’un contexte supplémentaire, vous pouvez aussi transmettre subid2 et subid3. Par exemple, certains éditeurs utilisent subid pour l’ID utilisateur, subid2 pour l’emplacement de l’application, et subid3 pour une campagne ou une étiquette de test A/B.

Étape 2 : commencez avec une URL de postback propre et fiable

Beaucoup de configurations de postback échouent parce qu’elles commencent trop larges. Gardez votre première version petite et fiable. Voici un excellent modèle de départ pour la plupart des éditeurs CPAlead :

https://example.com/postback/cpalead.php?subid={subid}&lead_id={lead_id}&campaign_id={campaign_id}&campaign_name={campaign_name}&payout={payout}&password={password}

Cette version vous donne les champs dont la plupart des éditeurs ont réellement besoin : qui récompenser, quel lead a converti, quelle offre a converti, combien elle a payé, et un secret partagé pour vérifier la requête.

Étape 3 : comprenez les macros recommandées

{subid} : votre propre ID utilisateur ou référence de transaction. Cela indique à votre système qui doit recevoir la récompense.
{lead_id} : l’ID de conversion unique de CPAlead. C’est le meilleur champ pour la protection contre les doublons et la sécurité en cas de nouvelle tentative.
{campaign_id} : l’ID de l’offre ou de la campagne CPAlead.
{campaign_name} : le nom de l’offre ou de la campagne CPAlead.
{payout} : le montant du paiement pour la conversion. La plupart des éditeurs devraient utiliser cela comme entrée de récompense.
{password} : votre secret de postback enregistré, que votre endpoint doit valider avant de créditer l’utilisateur.

Les macros optionnelles incluent {subid2}, {subid3}, {country_iso}, {ip_address}, {idfa}, {gaid} et {gateway_id}. CPAlead prend également en charge des alias de compatibilité tels que {offer_id}, {offer_name}, {transaction_id}, {amount}, {ip} et {country_code} si votre endpoint existant attend ces noms.

Une note importante : ne construisez pas votre première intégration autour de {virtual_currency}. Dans le flux standard de postback éditeur de CPAlead, cette valeur est généralement 0. Si vous avez besoin de points ou de monnaie intégrée à l’application, il est généralement préférable de les calculer à partir de {payout} dans votre propre système.

Étape 4 : sécurisez correctement l’endpoint

Ajoutez un mot de passe de postback dans votre tableau de bord CPAlead et incluez {password} dans l’URL. Sur votre serveur, vérifiez-le avant de récompenser l’utilisateur. C’est une méthode simple et efficace pour rejeter les requêtes non autorisées.

Si votre serveur n’accepte que des IP approuvées, ajoutez à la liste blanche l’IP de relais affichée dans votre tableau de bord de postback CPAlead. C’est l’IP sortante que CPAlead utilise pour les postbacks éditeur. Si vous n’ajoutez pas l’IP à la liste blanche, la validation par mot de passe devient encore plus importante.

Votre endpoint doit aussi renvoyer rapidement une réponse HTTP 2xx une fois la conversion traitée. Des réponses lentes ou non-2xx peuvent provoquer des nouvelles tentatives et des erreurs de postback.

Étape 5 : testez le postback avant d’envoyer du trafic réel

Après avoir enregistré votre URL de postback, utilisez la page de test de postback dans votre tableau de bord CPAlead. Un bon test confirme quatre points :

La requête atteint votre serveur. Si ce n’est pas le cas, vérifiez les règles du pare-feu, le SSL, la liste blanche d’IP ou le format de votre URL.
La réponse est HTTP 2xx. Votre endpoint doit renvoyer le succès rapidement après traitement de la requête.
Le mapping utilisateur est correct. Confirmez que {subid} correspond au bon utilisateur ou wallet dans votre système.
La protection contre les doublons fonctionne. Si le même {lead_id} est envoyé à nouveau, votre endpoint doit l’ignorer au lieu de récompenser l’utilisateur deux fois.

Après le test, consultez la page des journaux de postback dans votre tableau de bord CPAlead. C’est le moyen le plus rapide de confirmer l’URL de destination, le code de réponse et toute erreur de livraison à corriger.

Exemple de script PHP

Voici un exemple de départ plus sûr que de simplement mettre à jour un solde à partir de {subid} et {payout}. Il valide le mot de passe, stocke {lead_id} de manière unique pour sécuriser les nouvelles tentatives, et utilise des requêtes préparées au lieu de SQL brut.

<?php

declare(strict_types=1);

const POSTBACK_PASSWORD = 'replace_with_your_secret';

$subid = trim((string) ($_GET['subid'] ?? ''));
$leadId = (int) ($_GET['lead_id'] ?? 0);
$campaignId = (int) ($_GET['campaign_id'] ?? 0);
$payout = (float) ($_GET['payout'] ?? 0);
$password = (string) ($_GET['password'] ?? '');

if (POSTBACK_PASSWORD !== '' && !hash_equals(POSTBACK_PASSWORD, $password)) {
    http_response_code(403);
    exit('Invalid postback password.');
}

if ($subid === '' || $leadId <= 0) {
    http_response_code(400);
    exit('Missing subid or lead_id.');
}

$pdo = new PDO('mysql:host=127.0.0.1;dbname=your_database;charset=utf8mb4', 'user', 'pass', [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

$pdo->beginTransaction();

try {
    $insert = $pdo->prepare(
        'INSERT INTO cpalead_postbacks (lead_id, user_id, campaign_id, payout, created_at)
         VALUES (:lead_id, :user_id, :campaign_id, :payout, NOW())'
    );
    $insert->execute([
        ':lead_id' => $leadId,
        ':user_id' => $subid,
        ':campaign_id' => $campaignId,
        ':payout' => $payout,
    ]);
} catch (PDOException $e) {
    if (($e->errorInfo[1] ?? null) === 1062) {
        $pdo->rollBack();
        http_response_code(200);
        exit('Duplicate lead ignored.');
    }

    $pdo->rollBack();
    throw $e;
}

$credit = $pdo->prepare('UPDATE users SET balance = balance + :amount WHERE id = :user_id');
$credit->execute([
    ':amount' => $payout,
    ':user_id' => $subid,
]);

if ($credit->rowCount() !== 1) {
    $pdo->rollBack();
    http_response_code(404);
    exit('User not found.');
}

$pdo->commit();
http_response_code(200);
echo 'OK';

Si vous utilisez un système de points au lieu d’un solde en argent, convertissez {payout} selon votre propre ratio de points avant de mettre à jour l’utilisateur. Par exemple, si votre application utilise 100 points pour 1,00 $ gagné, calculez cette conversion dans votre propre code plutôt que de compter sur une macro séparée.

Et si vous ne voulez pas de crédit automatique ?

CPAlead prend aussi en charge une approche de secours plus simple pour certains éditeurs : vous pouvez demander au visiteur un e-mail ou un subID et examiner les conversions manuellement. Cela peut fonctionner pour de très petits projets, mais c’est plus lent, plus facile à créditer incorrectement, et beaucoup plus difficile à faire évoluer. Si vous voulez des récompenses utilisateur fiables, le crédit automatique via postback est la meilleure option.

Conseils finaux

Transmettez toujours votre propre référence utilisateur dans {subid}.
Stockez toujours {lead_id} et dédupliquez dessus.
Utilisez {payout} comme entrée principale de récompense.
Validez {password} avant de créditer.
Testez l’URL et consultez les journaux de postback avant d’envoyer du trafic réel.

Si vous suivez ce modèle, la configuration du postback de votre CPAlead Offerwall sera beaucoup plus facile à maintenir, plus simple à déboguer, et beaucoup moins susceptible de créditer les utilisateurs deux fois ou de perdre des conversions.

Vous avez remarqué une erreur ou un aspect de cet article qui nécessite une correction ? Merci de fournir le lien de l'article et contactez-nous. Nous apprécions vos commentaires et nous occuperons du problème rapidement.