数字产品交付

​

概述

• 托管文件上传：Dodo Payments 存储您的文件，并通过短时有效的预签名 URL 提供文件。
• 外部下载链接：每个权益可配置一个 URL，指向托管在其他位置的文件，例如 Dropbox、Google Drive 或 S3。
• 下载说明：在客户订单页面和交付邮件中向客户显示的自由文本。

​

关键功能

​

设置 Digital Product Delivery

1

Open Entitlements

在控制台中转到 Entitlements，然后点击 + 创建权益。

2

Choose Digital Files

选择 Digital Files，并为权益输入一个 Name。

3

Add Files, Links, and Instructions

配置以下字段的任意组合：

• Upload files：上传一个或多个文件。每次上传都会返回 file_id，并将文件添加到权益的 digital_file_ids 中。
• External Download Link：一个以 http:// 或 https:// 开头、客户可以访问的 URL。Dodo Payments 会将其与托管文件一同交付。
• Instructions：向客户显示的自由文本，例如“解压并运行 setup.sh。”

4

Save the Entitlement

点击 Create Entitlement。现在，您可以将该权益附加到任何产品。

​

附加到产品

​

交付工作原理

​

客户体验

​

购买确认

​

客户门户访问

​

程序化管理文件

​

将文件上传到权益

import DodoPayments from 'dodopayments';
import { openAsBlob } from 'node:fs'; // Node.js 20 or later

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  environment: 'test_mode',
});

// The SDK sends a FormData body as multipart/form-data. Append `filename` before `file`.
const form = new FormData();
form.append('filename', 'pro-bundle.zip');
form.append('file', await openAsBlob('./pro-bundle.zip'), 'pro-bundle.zip');

const { file_id } = await client.entitlements.files.upload('ent_files_abc', { body: form });
console.log(file_id);

curl -X POST "https://test.dodopayments.com/entitlements/ent_files_abc/files" \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -F "filename=pro-bundle.zip" \
  -F "file=@./pro-bundle.zip"

​

列出授予并解析下载 URL

const grants = await client.entitlements.grants.list('ent_files_abc', {
  customer_id: 'cus_abc123',
});

for (const grant of grants.items) {
  for (const file of grant.digital_product_delivery?.files ?? []) {
    console.log(file.filename, file.download_url, `expires in ${file.expires_in}s`);
  }
}

​

从权益中移除文件

await client.entitlements.files.delete('YOUR_FILE_ID', { id: 'ent_files_abc' });

​

重要注意事项

• **预签名 URL 很快就会过期。**授予 payload 和 webhook 事件中的下载 URL 有效期为 15 分钟。不要存储这些 URL。客户需要再次下载时，请获取新的 URL。
• **更新文件只会影响未来的购买。**替换或移除文件不会改变已经发放的下载内容。每个授予都会保留其创建时的权益配置，因此过去的客户仍可获取当时有效的版本。
• **退款不会使已下载的副本失效。**已经下载文件的客户会保留该副本。对于许可证受限媒体或限时访问等可撤销内容，请将 Digital Files 与 License Keys 搭配使用，并在运行时验证密钥。
• **对于敏感内容，建议使用带有独立身份验证的外部 URL。**Dodo Payments 的预签名 URL 有效期较短，但任何拥有该 URL 的人都可以在其过期前下载文件。将外部托管内容置于账户登录保护之后，可以让您获得更多控制权。

​

API 管理

​

Webhooks

"digital_product_delivery": {
  "files": [
    {
      "file_id": "YOUR_FILE_ID",
      "download_url": "https://files.dodopayments.com/.../pro-bundle.zip?Signature=...",
      "filename": "pro-bundle.zip",
      "content_type": "application/zip",
      "file_size": 18742390,
      "expires_in": 900
    }
  ],
  "instructions": "Unzip and run setup.sh from the project root.",
  "external_url": null
}

​

Legacy Digital Product Delivery

​

最佳实践

• **将下载视为一次性交付。**客户可能会分享或丢失链接，因此应基于客户下载的任何内容都归其所有这一前提来设计产品。
• **使用说明明确客户预期。**对于多文件捆绑包，请添加一行 instructions，说明应先安装什么或如何组合文件。
• **注意 500 MiB 上限。**对于多 GB 数据集或视频课程等较大的资源，请将其托管在外部，并使用 external_url 链接到这些资源，而不是上传它们。
• **与 License Keys 结合使用以实现可撤销访问。**要在退款后撤销客户对产品内功能的访问权限，请将 Digital Files 权益与 License Key 权益搭配使用，并在运行时验证密钥。
• **测试 Customer Portal 刷新流程。**确认客户一周后返回门户时，仍能获取有效的下载链接。邮件链接过期后，门户是主要的恢复途径。