Back to Details

stripe-affiliate-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Stripe Affiliate Integration

Stripe 联盟计划集成

This skill guides you through setting up Affonso affiliate tracking with Stripe payment integration.
本Skill将指导您完成Affonso联盟追踪与Stripe支付的集成设置。

Overview

概述

Affonso is an affiliate program platform that tracks referrals and commissions. This skill helps implement:
  1. Tracking script installation - Monitor affiliate traffic and conversions
  2. Stripe integration - Pass referral data to Stripe for commission tracking
  3. Optional features - Signup tracking, GTM integration, GDPR compliance
Affonso是一个用于追踪推荐和佣金的联盟计划平台。本Skill可帮助实现：
  1. 追踪脚本安装 - 监控联盟流量和转化
  2. Stripe集成 - 将推荐数据传递给Stripe以进行佣金追踪
  3. 可选功能 - 注册追踪、GTM集成、GDPR合规

Prerequisites & Information Gathering

前提条件与信息收集

Before beginning implementation, gather the following information by asking the user:
在开始实施之前，请通过询问用户收集以下信息：

Required Information

所需信息

  1. Program ID: Ask "What is your Affonso program ID? You can find it at https://affonso.io/app/affiliate-program"
  2. Cookie Duration: Ask "How many days should the affiliate tracking cookie persist? (Common values: 30, 60, 90 days)"
  3. Stripe Integration Method: Ask "How do you communicate with Stripe?" Provide options:
    • Stripe Checkout API
    • Stripe Payment Links
    • Stripe Buy Button
    • Stripe Pricing Tables
    • I don't know / Need help determining this
  4. Google Tag Manager: Ask "Do you use Google Tag Manager to manage scripts on your website?"
  5. Cookie Consent Banner: Ask "Do you use a cookie consent banner or need GDPR compliance?" If yes, follow up with "Which cookie consent platform do you use?" (e.g., Cookiebot, OneTrust, CookieYes, custom solution)
  1. 计划ID：询问“您的Affonso计划ID是什么？您可以在 https://affonso.io/app/affiliate-program 找到它”
  2. Cookie有效期：询问“联盟追踪Cookie的有效期应为多少天？（常见值：30、60、90天）”
  3. Stripe集成方式：询问“您通过哪种方式与Stripe对接？”提供以下选项：
    • Stripe Checkout API
    • Stripe Payment Links
    • Stripe Buy Button
    • Stripe Pricing Tables
    • 我不知道 / 需要帮助确定
  4. Google Tag Manager：询问“您是否使用Google Tag Manager管理网站上的脚本？”
  5. Cookie同意横幅：询问“您是否使用Cookie同意横幅，或者需要符合GDPR要求？”如果是，追问“您使用哪个Cookie同意平台？”（例如：Cookiebot、OneTrust、CookieYes、自定义方案）

Optional Features

可选功能

  1. Signup Tracking: Ask "Do you want to track user signups in addition to purchases? (Recommended - provides better insights on affiliate performance)"
  1. 注册追踪：询问“除了购买之外，您是否还想追踪用户注册？（推荐 - 可提供更深入的联盟效果洞察）”

Connect Payment Provider

连接支付提供商

If the user's Stripe account is not already connected in Affonso, tell them to do this before or alongside the code integration:
  1. Go to https://affonso.io/app/affiliate-program/connect
  2. Select Stripe
  3. Enter the Stripe API key
  4. Copy the webhook URL that Affonso provides
  5. Add that webhook URL in the Stripe dashboard
If Stripe is already connected, continue with the code changes and keep the existing webhook connection in place.
如果用户的Stripe账户尚未在Affonso中连接，请告知他们在代码集成之前或同步完成此操作：
  1. 访问 https://affonso.io/app/affiliate-program/connect
  2. 选择Stripe
  3. 输入Stripe API密钥
  4. 复制Affonso提供的webhook URL
  5. 在Stripe仪表板中添加该webhook URL
如果Stripe已连接，请继续进行代码修改，并保留现有的webhook连接。

Workflow Decision Tree

工作流决策树

1. Connect Stripe to Affonso if it is not connected yet

2. Install Tracking Script
   ├─ Uses GTM? → See GTM Integration Guide
   ├─ Has Cookie Consent? → See GDPR Consent Guide
   └─ Neither → Direct script installation

3. Track Signups (Optional)
   └─ Add signup tracking code

4. Pass Data to Stripe
   ├─ Checkout API → See Stripe Checkout API Guide
   ├─ Payment Links → See Payment Links Guide
   ├─ Buy Button → See Buy Button Guide
   ├─ Pricing Tables → See Pricing Tables Guide
   └─ Don't Know → Help identify integration method

5. Test Integration
   └─ Verify tracking works end-to-end
1. 如果尚未连接，先将Stripe连接到Affonso

2. 安装追踪脚本
   ├─ 使用GTM？ → 参见GTM集成指南
   ├─ 有Cookie同意？ → 参见GDPR同意指南
   └─ 都没有 → 直接脚本安装

3. 追踪注册（可选）
   └─ 添加注册追踪代码

4. 将数据传递给Stripe
   ├─ Checkout API → 参见Stripe Checkout API指南
   ├─ Payment Links → 参见Payment Links指南
   ├─ Buy Button → 参见Buy Button指南
   ├─ Pricing Tables → 参见Pricing Tables指南
   └─ 不知道 → 帮助确定集成方式

5. 测试集成
   └─ 端到端验证追踪是否正常工作

Step 1: Install Tracking Script

步骤1：安装追踪脚本

The tracking script monitors affiliate traffic and creates the 
affonso_referral
cookie that gets passed to Stripe.
追踪脚本会监控联盟流量，并创建
affonso_referral
Cookie，该Cookie会被传递给Stripe。

Decision: GTM vs Direct Installation

决策：GTM 与 直接安装

If user uses Google Tag Manager:
  • Read and follow the GTM Integration Guide
  • This includes instructions for creating the GTM tag, setting triggers, and publishing
If user does NOT use GTM:
  • Continue with direct script installation below
如果用户使用Google Tag Manager：
  • 阅读并遵循GTM集成指南
  • 其中包含创建GTM代码、设置触发器和发布的说明
如果用户不使用GTM：
  • 继续阅读下方的直接脚本安装说明

Direct Script Installation

直接脚本安装

Basic Installation (No Cookie Consent)

基础安装（无Cookie同意）

Add this script to the website's 
<head>
tag:
html
<!-- Place in <head> tag -->
<script
  async
  defer
  src="https://cdn.affonso.io/js/pixel.min.js"
  data-affonso="YOUR_PUBLIC_PROGRAM_ID"
  data-cookie_duration="YOUR_COOKIE_DURATION"
></script>
  • Replace 
    YOUR_PUBLIC_PROGRAM_ID
    with the user's program ID
  • Replace 
    YOUR_COOKIE_DURATION
    with the cookie duration (e.g., 
    30
    for 30 days)
将此脚本添加到网站的
<head>
标签中：
html
<!-- Place in <head> tag -->
<script
  async
  defer
  src="https://cdn.affonso.io/js/pixel.min.js"
  data-affonso="YOUR_PUBLIC_PROGRAM_ID"
  data-cookie_duration="YOUR_COOKIE_DURATION"
></script>
  • 将
    YOUR_PUBLIC_PROGRAM_ID
    替换为用户的计划ID
  • 将
    YOUR_COOKIE_DURATION
    替换为Cookie有效期（例如：
    30
    代表30天）

GDPR/Cookie Consent Installation

GDPR/Cookie同意安装

If the user has a cookie consent banner, read and follow the GDPR Consent Guide which includes:
  • How to enable consent mode with 
    data-requires-consent="true"
  • Integration code for popular consent platforms (Cookiebot, OneTrust, CookieYes, etc.)
  • URL parameter propagation requirements
  • Testing consent-based tracking
Consent-enabled script:
html
<script
  async
  defer
  src="https://cdn.affonso.io/js/pixel.min.js"
  data-affonso="YOUR_PUBLIC_PROGRAM_ID"
  data-cookie_duration="YOUR_COOKIE_DURATION"
  data-requires-consent="true"
></script>
Then add consent callback integration based on their consent platform (see GDPR guide).
如果用户有Cookie同意横幅，请阅读并遵循GDPR同意指南，其中包含：
  • 如何通过
    data-requires-consent="true"
    启用同意模式
  • 主流同意平台的集成代码（Cookiebot、OneTrust、CookieYes等）
  • URL参数传递要求
  • 基于同意的追踪测试
启用同意模式的脚本：
html
<script
  async
  defer
  src="https://cdn.affonso.io/js/pixel.min.js"
  data-affonso="YOUR_PUBLIC_PROGRAM_ID"
  data-cookie_duration="YOUR_COOKIE_DURATION"
  data-requires-consent="true"
></script>
然后根据他们的同意平台添加同意回调集成（参见GDPR指南）。

Step 2: Track User Signups (Optional)

步骤2：追踪用户注册（可选）

If the user wants to track signups, add this code after their user registration logic:
javascript
// After successful user registration
window.Affonso.signup(userEmail);
Benefits of signup tracking:
  • See which affiliates drive the most registrations
  • Calculate conversion rates from clicks to signups
  • Optimize funnel based on affiliate performance
如果用户想要追踪注册，请在其用户注册逻辑之后添加以下代码：
javascript
// After successful user registration
window.Affonso.signup(userEmail);
注册追踪的优势：
  • 查看哪些联盟客带来的注册量最多
  • 计算从点击到注册的转化率
  • 根据联盟表现优化转化漏斗

Step 3: Pass Referral Data to Stripe

步骤3：将推荐数据传递给Stripe

The tracking script creates an 
affonso_referral
cookie that must be passed to Stripe. Implementation varies by Stripe integration method.
追踪脚本会创建
affonso_referral
Cookie，必须将其传递给Stripe。具体实现方式因Stripe集成方式而异。

Identify Stripe Integration Method

确定Stripe集成方式

If the user selected "I don't know", help them identify their integration method:
  • Checkout API: They create Stripe sessions programmatically in backend code (Node.js, Python, PHP, etc.)
  • Payment Links: They use links starting with 
    buy.stripe.com
    that redirect to Stripe's hosted checkout
  • Buy Button: They embed 
    <stripe-buy-button>
    HTML elements on their website
  • Pricing Tables: They embed 
    <stripe-pricing-table>
    HTML elements on their website
如果用户选择“我不知道”，请帮助他们确定其集成方式：
  • Checkout API：他们在后端代码中以编程方式创建Stripe会话（Node.js、Python、PHP等）
  • Payment Links：他们使用以
    buy.stripe.com
    开头的链接，重定向到Stripe托管的结账页面
  • Buy Button：他们在网站上嵌入
    <stripe-buy-button>
    HTML元素
  • Pricing Tables：他们在网站上嵌入
    <stripe-pricing-table>
    HTML元素

Integration Guides

集成指南

Based on the identified method, read and implement the appropriate guide:
根据确定的方式，阅读并实施相应的指南：

Stripe Checkout API

Stripe Checkout API

When to use: User creates checkout sessions programmatically in backend code
Read Stripe Checkout API Guide which includes:
  • How to pass 
    affonso_referral
    cookie as metadata
  • Framework-specific examples (Next.js, Node.js, Python, Ruby, PHP)
  • Testing with server logs
Quick implementation (Next.js example):
javascript
import { cookies } from 'next/headers';

const cookieStore = await cookies();
const affonsoReferral = cookieStore.get('affonso_referral')?.value || '';

const session = await stripe.checkout.sessions.create({
  // ... existing config
  metadata: {
    affonso_referral: affonsoReferral,
  },
});
适用场景：用户在后端代码中以编程方式创建结账会话
阅读Stripe Checkout API指南，其中包含：
  • 如何将
    affonso_referral
    Cookie作为metadata传递
  • 特定框架的示例（Next.js、Node.js、Python、Ruby、PHP）
  • 使用服务器日志进行测试
快速实现（Next.js示例）：
javascript
import { cookies } from 'next/headers';

const cookieStore = await cookies();
const affonsoReferral = cookieStore.get('affonso_referral')?.value || '';

const session = await stripe.checkout.sessions.create({
  // ... existing config
  metadata: {
    affonso_referral: affonsoReferral,
  },
});

Stripe Payment Links

Stripe Payment Links

When to use: User has links starting with 
buy.stripe.com
Read Payment Links Guide which includes:
  • Enhancement script that automatically appends 
    client_reference_id
    to links
  • How the script works and when it runs
  • Testing procedures
适用场景：用户拥有以
buy.stripe.com
开头的链接
阅读Payment Links指南，其中包含：
  • 自动向链接追加
    client_reference_id
    的增强脚本
  • 脚本的工作原理和运行时机
  • 测试流程

Stripe Buy Button

Stripe Buy Button

When to use: User has 
<stripe-buy-button>
elements
Read Buy Button Guide which includes:
  • Enhancement script that sets 
    client-reference-id
    attribute
  • Installation instructions
  • Testing procedures
适用场景：用户拥有
<stripe-buy-button>
元素
阅读Buy Button指南，其中包含：
  • 设置
    client-reference-id
    属性的增强脚本
  • 安装说明
  • 测试流程

Stripe Pricing Tables

Stripe Pricing Tables

When to use: User has 
<stripe-pricing-table>
elements
Read Pricing Tables Guide which includes:
  • Enhancement script that sets 
    client-reference-id
    attribute
  • Installation instructions
  • Testing procedures
适用场景：用户拥有
<stripe-pricing-table>
元素
阅读Pricing Tables指南，其中包含：
  • 设置
    client-reference-id
    属性的增强脚本
  • 安装说明
  • 测试流程

Step 4: Testing & Verification

步骤4：测试与验证

Test Tracking Script

测试追踪脚本

  1. Visit the website with test parameter: 
    yoursite.com?atp=test
  2. Open browser DevTools → Application → Cookies
  3. Verify 
    affonso_referral
    cookie is set (unless consent mode is enabled and consent not given)
  4. Check Affonso dashboard for test entry
  1. 携带测试参数访问网站：
    yoursite.com?atp=test
  2. 打开浏览器DevTools → 应用（Application） → Cookie
  3. 验证
    affonso_referral
    Cookie已设置（除非启用了同意模式且用户未给予同意）
  4. 在Affonso仪表板中检查测试记录

Test Stripe Integration

测试Stripe集成

For Checkout API:
  • Trigger checkout flow and check server logs for 
    metadata: { affonso_referral: "..." }
For Payment Links, Buy Buttons, Pricing Tables:
  • Inspect the enhanced elements/URLs to verify 
    client_reference_id
    is added
  • DevTools → Elements tab → Find the Stripe element and check attributes/URL
对于Checkout API：
  • 触发结账流程，检查服务器日志中是否有
    metadata: { affonso_referral: "..." }
对于Payment Links、Buy Buttons、Pricing Tables：
  • 检查增强后的元素/URL，验证
    client_reference_id
    已添加
  • DevTools → 元素（Elements）标签页 → 找到Stripe元素，检查属性/URL

End-to-End Test

端到端测试

  1. Visit site with 
    ?atp=test
    parameter
  2. Complete a purchase using a 100% discount code (for live testing without payment)
  3. Check Affonso dashboard to verify the conversion was tracked
  4. Verify the test affiliate received credit for the sale
Note: Stripe test mode transactions won't appear in Affonso - use discount codes on live mode or check server logs/element attributes.
  1. 携带
    ?atp=test
    参数访问网站
  2. 使用100%折扣码完成购买（用于无需支付的正式环境测试）
  3. 检查Affonso仪表板，验证转化已被追踪
  4. 验证测试联盟客已获得该笔销售的佣金
注意： Stripe测试模式的交易不会出现在Affonso中 - 请在正式模式下使用折扣码，或检查服务器日志/元素属性。

GDPR Consent Testing

GDPR同意测试

If using consent mode:
  1. Visit site with 
    ?atp=test
    - verify no cookie is set
  2. Accept cookies through consent banner - verify cookie is now set
  3. Navigate between pages - verify 
    affonso_id
    parameter persists
  4. Complete purchase - verify tracking works
如果使用同意模式：
  1. 携带
    ?atp=test
    访问网站 - 验证未设置Cookie
  2. 通过同意横幅接受Cookie - 验证现在已设置Cookie
  3. 在页面间导航 - 验证
    affonso_id
    参数持续存在
  4. 完成购买 - 验证追踪正常工作

Troubleshooting

故障排查

Cookie Not Set

Cookie未设置

  • Check that script is in 
    <head>
    tag
  • Verify program ID is correct
  • If using consent mode, ensure 
    window.affonsoConsentGranted()
    is called after user accepts
  • 检查脚本是否位于
    <head>
    标签中
  • 验证计划ID是否正确
  • 如果使用同意模式，确保在用户接受后调用
    window.affonsoConsentGranted()

Stripe Not Receiving Data

Stripe未接收到数据

  • Checkout API: Verify server code reads cookie and passes to metadata
  • Payment Links/Buy Button/Pricing Tables: Check that enhancement script runs (look for 
    affonso_referral_ready
    event)
  • Inspect Network tab for script loading errors
  • Checkout API：验证服务器代码读取了Cookie并将其传递到metadata中
  • Payment Links/Buy Button/Pricing Tables：检查增强脚本是否运行（查找
    affonso_referral_ready
    事件）
  • 检查网络（Network）标签页中是否有脚本加载错误

Tracking Not Appearing in Dashboard

追踪记录未出现在仪表板中

  • Ensure Stripe is connected in Affonso dashboard. If not, connect it first at https://affonso.io/app/affiliate-program/connect and add the Affonso webhook in Stripe.
  • For testing, use live mode with discount codes (test mode doesn't sync)
  • Check that the purchase completed successfully in Stripe
  • 确保Stripe已在Affonso仪表板中连接。如果没有，请先在 https://affonso.io/app/affiliate-program/connect 连接，并在Stripe中添加Affonso的webhook。
  • 测试时，请使用带折扣码的正式模式（测试模式不会同步）
  • 检查Stripe中的购买是否已成功完成

Additional Resources

更多资源

For framework-specific implementation guidance, the user can check:
如需特定框架的实施指导，用户可以查看：

Next Steps

后续步骤

After successful integration:
  1. Set up affiliate recruitment and program rules in Affonso dashboard
  2. Create affiliate resources (landing pages, promotional materials)
  3. Monitor performance and optimize commission structure
集成成功后：
  1. 在Affonso仪表板中设置联盟客招募和计划规则
  2. 创建联盟资源（落地页、宣传材料）
  3. 监控表现并优化佣金结构