API 参考

设置

“设置” API 允许你管理应用范围的配置，例如通知规则或捐赠小部件的参数。这些设置功能多样，可以针对应用中的不同类型的组件或功能进行定制。
每个设置通过 mountLocation 进行标识，并具有特定的 type，该 type 决定了其 settings 对象的结构。
设置对象#设置对象代表应用中的一个特定配置，包含以下属性：
属性
类型
描述
id
string
设置的唯一标识符。
livemode
boolean
如果对象存在于生产模式，则为 true；如果存在于测试模式，则为 false。
type
string
设置的类型（例如 'donate'、'notification'）。这决定了 settings 对象的结构。
mount_location
string
应用此设置的组件或位置的标识符。
active
boolean
如果设置为当前激活状态，则为 true。
component_did
string
（可选）与此设置关联的组件的 DID。
description
string
对设置用途的描述。
settings
object
包含详细配置的对象，其结构取决于 type 字段。
created_at
Date
创建设置时的时间戳。
updated_at
Date
上次更新设置时的时间戳。
创建设置#为指定的挂载位置和类型创建新设置。
参数#名称
类型
描述
mountLocation
string
**必需。**设置使用位置的唯一标识符。
description
string
**必需。**对设置的人类可读描述。
type
string
**必需。**要创建的设置类型，例如 'notification' 或 'donate'。
settings
object
**必需。**一个配置对象，其结构取决于 type。请参阅下面的示例。
settings.amount
object
用于 donate 类型。包含金额设置：presets (string[])、preset (string)、custom (boolean)、minimum (string)、maximum (string)。
settings.btnText
string
用于 donate 类型。捐赠按钮上显示的文本。
settings.historyType
`'table'
'avatar'`
settings.self_handle
boolean
用于 notification 类型。如果为 true，表示通知由应用程序自行处理。
settings.exclude_events
string[]
用于 notification 类型。要从通知中排除的事件类型数组。
settings.include_events
string[]
用于 notification 类型。要包含在通知中的事件类型数组。
active
boolean
（可选） 设置是否激活。默认为 true。
livemode
boolean
（可选） 此设置是否应用于生产模式。
componentDid
string
（可选） 组件的 DID。
返回#返回新创建的设置对象。
示例#async function createNotificationSetting() {
  try {
    const setting = await payment.settings.create({
      type: 'notification',
      mountLocation: 'user_dashboard_notifications',
      description: '控制主用户仪表板的通知。',
      active: true,
      settings: {
        self_handle: false,
        include_events: ['customer.subscription.renewed', 'invoice.paid'],
      },
    });
    console.log('设置已创建：', setting);
  } catch (error) {
    console.error('创建设置时出错：', error.message);
  }
}

createNotificationSetting();示例响应#{
  "id": "set_1J2K3L4M5N6O7P8Q",
  "livemode": false,
  "type": "notification",
  "mount_location": "user_dashboard_notifications",
  "active": true,
  "component_did": null,
  "description": "控制主用户仪表板的通知。",
  "settings": {
    "self_handle": false,
    "include_events": [
      "customer.subscription.renewed",
      "invoice.paid"
    ]
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}检索设置#通过设置的 ID 或挂载位置检索其详细信息。
参数#名称
类型
描述
mountLocationOrId
string
**必需。**要检索的设置的唯一标识符或挂载位置。
返回#返回检索到的设置对象。
示例#async function getSettingDetails(id) {
  try {
    const setting = await payment.settings.retrieve(id);
    console.log('设置详情：', setting);
  } catch (error) {
    console.error(`检索设置 ${id} 时出错：`, error.message);
  }
}

getSettingDetails('set_1J2K3L4M5N6O7P8Q');示例响应#{
  "id": "set_1J2K3L4M5N6O7P8Q",
  "livemode": false,
  "type": "notification",
  "mount_location": "user_dashboard_notifications",
  "active": true,
  "component_did": null,
  "description": "控制主用户仪表板的通知。",
  "settings": {
    "self_handle": false,
    "include_events": [
      "customer.subscription.renewed",
      "invoice.paid"
    ]
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:05:00.000Z"
}更新设置#更新现有设置的属性。你可以修改其状态、描述或嵌套的 settings 对象。
参数#名称
类型
描述
mountLocationOrId
string
**必需。**要更新的设置的标识符或挂载位置。
updateData
object
**必需。**一个包含要更新字段的对象。
updateData.active
boolean
（可选） 设置的新激活状态。
updateData.description
string
（可选） 设置的新描述。
updateData.settings
object
（可选） 与现有设置合并的部分对象。
返回#返回更新后的设置对象。
示例#async function updateSetting(id) {
  try {
    const updatedSetting = await payment.settings.update(id, {
      description: '已更新仪表板通知设置。',
      settings: {
        exclude_events: ['invoice.created'],
      },
    });
    console.log('设置已更新：', updatedSetting);
  } catch (error) {
    console.error(`更新设置 ${id} 时出错：`, error.message);
  }
}

updateSetting('set_1J2K3L4M5N6O7P8Q');示例响应#{
  "id": "set_1J2K3L4M5N6O7P8Q",
  "livemode": false,
  "type": "notification",
  "mount_location": "user_dashboard_notifications",
  "active": true,
  "component_did": null,
  "description": "已更新仪表板通知设置。",
  "settings": {
    "self_handle": false,
    "include_events": [
      "customer.subscription.renewed",
      "invoice.paid"
    ],
    "exclude_events": [
      "invoice.created"
    ]
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:10:00.000Z"
}删除设置#永久删除一个设置。
参数#名称
类型
描述
mountLocationOrId
string
**必需。**要删除的设置的标识符或挂载位置。
返回#返回一个包含确认消息的对象。
示例#async function deleteSetting(id) {
  try {
    const response = await payment.settings.del(id);
    console.log(response.message);
  } catch (error) {
    console.error(`删除设置 ${id} 时出错：`, error.message);
  }
}

deleteSetting('set_1J2K3L4M5N6O7P8Q');示例响应#{
  "message": "设置已成功删除"
}
本指南介绍了如何管理应用设置。要了解如何跟踪基于用量的计费，请继续阅读 Meters 部分。

属性	类型	描述
`id`	`string`	设置的唯一标识符。
`livemode`	`boolean`	如果对象存在于生产模式，则为 `true`；如果存在于测试模式，则为 `false`。
`type`	`string`	设置的类型（例如 `'donate'`、`'notification'`）。这决定了 `settings` 对象的结构。
`mount_location`	`string`	应用此设置的组件或位置的标识符。
`active`	`boolean`	如果设置为当前激活状态，则为 `true`。
`component_did`	`string`	（可选）与此设置关联的组件的 DID。
`description`	`string`	对设置用途的描述。
`settings`	`object`	包含详细配置的对象，其结构取决于 `type` 字段。
`created_at`	`Date`	创建设置时的时间戳。
`updated_at`	`Date`	上次更新设置时的时间戳。

名称	类型	描述
`mountLocation`	`string`	必需。设置使用位置的唯一标识符。
`description`	`string`	必需。对设置的人类可读描述。
`type`	`string`	必需。要创建的设置类型，例如 `'notification'` 或 `'donate'`。
`settings`	`object`	必需。一个配置对象，其结构取决于 `type`。请参阅下面的示例。
`settings.amount`	`object`	用于 `donate` 类型。包含金额设置：`presets` (string[])、`preset` (string)、`custom` (boolean)、`minimum` (string)、`maximum` (string)。
`settings.btnText`	`string`	用于 `donate` 类型。捐赠按钮上显示的文本。
`settings.historyType`	`'table'	'avatar'`
`settings.self_handle`	`boolean`	用于 `notification` 类型。如果为 `true`，表示通知由应用程序自行处理。
`settings.exclude_events`	`string[]`	用于 `notification` 类型。要从通知中排除的事件类型数组。
`settings.include_events`	`string[]`	用于 `notification` 类型。要包含在通知中的事件类型数组。
`active`	`boolean`	（可选）设置是否激活。默认为 `true`。
`livemode`	`boolean`	（可选）此设置是否应用于生产模式。
`componentDid`	`string`	（可选）组件的 DID。

名称	类型	描述
`mountLocationOrId`	`string`	必需。要更新的设置的标识符或挂载位置。
`updateData`	`object`	必需。一个包含要更新字段的对象。
`updateData.active`	`boolean`	（可选）设置的新激活状态。
`updateData.description`	`string`	（可选）设置的新描述。
`updateData.settings`	`object`	（可选）与现有设置合并的部分对象。

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

设置

设置对象#

创建设置#

参数#

返回#

示例#

示例响应#

检索设置#

参数#

返回#

示例#

示例响应#

更新设置#

参数#

返回#

示例#

示例响应#

删除设置#

参数#

返回#

示例#

示例响应#

退款

计量器