Apples 平台 API 节点

用于苹果Ads平台API的Node.js / TypeScript客户端库.

模型和端点文档

该图书馆是安装和使用该图书馆的主要文件。 对于 关于数据模型和API端点的信息,见 Apple Ads 平台 API 文档 在苹果公司的开发商网站上找到.

安装

从 npm 安装此库 。 就像几乎任何软件依赖,你应该针 特定版本,仅在您明确打算时更新.

npm install @apple/apple-ads-platform

或者把它加进你的 package.json dependencies数字 :

{
  "dependencies": {
    "@apple/apple-ads-platform": "VERSION"
  }
}

载有类型Script申报的图书馆船——没有单独的 @types/... 需要软件包.

开始

这个图书馆很容易创建 AppleAdsApi 实例 a 一个 axios HTTP客户端已准备好呼叫苹果Ads平台API. 这个 createAppleAdsApi 工厂接受认证所需的信息 和各种可选设置。 由此产生的客户端透明地执行 OAuth 流量 .

客户建设

您可以以三种方式即时处理客户端, 由 authMode 选项对象上的字段.

使用您的私钥

创建客户端的第一个方法是提供一条通往您的路径 .pem 私有密钥文件与 其他相关的元数据。 图书馆在施工时读过钥匙一次 每次需要新的访问令牌时都会生成新的客户端秘密.

import { createAppleAdsApi } from '@apple/apple-ads-platform';

const api = await createAppleAdsApi({
  authMode: 'key',
  clientId: '...',
  teamId: '...',
  keyId: '...',
  privateKeyPath: '/path/to/your/private/key.pem',
});

使用自定义客户端加密工具

如果您希望以不同的方式生成客户机密(例如,生成其离线和 在运行时使用固定服务,或在签字时使用单独的服务),通过执行 ClientSecretProvider。图书馆在需要客户端保密时使用它 用于获取新的访问符.

import { createAppleAdsApi, ClientSecretProvider } from '@apple/apple-ads-platform';

const clientSecretProvider: ClientSecretProvider = {
  getClientSecret: () => '...',
};

const api = await createAppleAdsApi({
  authMode: 'clientSecret',
  clientId: '...',
  clientSecretProvider,
});

执行 OAuth 自己

我们建议让图书馆处理OAuth的流量 有具体要求的,可以 用一个 AccessTokenProvider。在这种情况下,图书馆在每一个API之前都叫它 请求以附加一个访问符作为 HTTP 标题.

import { createAppleAdsApi, AccessTokenProvider } from '@apple/apple-ads-platform';

const accessTokenProvider: AccessTokenProvider = new MyAccessTokenProvider(/* ... */);

const api = await createAppleAdsApi({
  authMode: 'token',
  accessTokenProvider,
});

可选设置

下面的所有选项都有合理的默认,可能会被省略. 选项作为字段在 相同的选项对象.

常见 authMode 数值)

增加额用于 authMode: 'key' 财务报告和审定财务报表 authMode: 'clientSecret'

可选设置示例

const api = await createAppleAdsApi({
  authMode: 'key',
  clientId: '...',
  teamId: '...',
  keyId: '...',
  privateKeyPath: '/path/to/your/private/key.pem',
  apiTimeout: 10_000,
  requestLogLevel: 'debug',
});

实例

这个 xApContext 标出该请求适用的广告账户. 这是一个简单的字符串——按照API的要求为您所呼叫的终点构建它.

查询活动

import {
  createAppleAdsApi,
  QueryRequest,
  QueryFilterOperator,
  CampaignSystemStatus,
} from '@apple/apple-ads-platform';

const api = await createAppleAdsApi({
  authMode: 'key',
  clientId: '...',
  teamId: '...',
  keyId: '...',
  privateKeyPath: '/path/to/your/private/key.pem',
});

const runningCampaignsRequest: QueryRequest = {
  filters: [
    {
      field: 'systemStatus',
      operator: QueryFilterOperator.Equals,
      value: CampaignSystemStatus.Running,
    },
  ],
};

const xApContext = '...'; // e.g. "adAccountId=12345678;" 

const response = await api.campaignsQueryPost(xApContext, runningCampaignsRequest);

通过 ID 获取商务品牌

const api = await createAppleAdsApi({
  authMode: 'key',
  clientId: '...',
  teamId: '...',
  keyId: '...',
  privateKeyPath: '/path/to/your/private/key.pem',
});

const brandId = '...';
const xApContext = '...';

const response = await api.getBrand(xApContext, brandId);

更新关键字标注

import { createAppleAdsApi, KeywordUpdate } from '@apple/apple-ads-platform';

const api = await createAppleAdsApi({
  authMode: 'key',
  clientId: '...',
  teamId: '...',
  keyId: '...',
  privateKeyPath: '/path/to/your/private/key.pem',
});

const keywordId = '...';
const xApContext = '...';

const keywordUpdate: KeywordUpdate = {
  bid: { amount: '1.00', currency: 'USD' },
};

const response = await api.keywordsIdPut(keywordId, xApContext, keywordUpdate);

处理错误

每个失败的请求——非-2xx响应或运输/网络故障——被转换为 ApiRequestError 在它逃出图书馆之前 错误是平整的 可序列( 安全到 JSON.stringify 它只载着平板球code, (中文(简体) ), status, (中文(简体) ), statusText, (中文(简体) ), method, (中文(简体) ), url加服务器的应答有效载荷(data) (中文(简体) ). 从来没有 保留了基本的轴误差、套接字或连接池代理.

import { ApiRequestError } from '@apple/apple-ads-platform';

try {
  await api.getBrand(xApContext, brandId);
} catch (err) {
  if (err instanceof ApiRequestError) {
    console.error(err.status, err.data);
  }
  throw err;
}

保存您的身份证明

你的私人密钥和客户秘密是敏感的证明 别把它们当作纯正的文字. 把访问符也当作秘密 库中不记录任何这些值( Authorization 页眉在日志输出中被明确省略). 如果您选择添加任何 通过客户端的更定制,增加记录或可观察性.

重用客户端

在许多飞行请求中,客户可以安全地同时使用。 创建单一实例 并在整个应用程序中分享。 最大限度地扩大 内置的保持-活性连接池并最小化给 OAuth 服务器的呼叫. 如果你提供你的 拥有 AccessTokenProvider,货币行为取决于执行.

元素类型

模型定义使用 TypeScript enum 有字符串值的类型(参见 src/model) 整个API模型. 随着API本身随时间演变,新的enum 值可能会出现。 因为库中不会显示未知的enum值 解序列化,一个响应可以包含一个不匹配当前任何成员的字符串 um. 与已知的馆员相比,请注意,并更新图书馆,以确保 您有匹配最新版本API的模型类型.

节点命令

测试

npm test

运行完整测试套房一次并报告结果. 使用此功能进行CI或快速本地检查 .

npm run test:coverage

运行完整的测试套件并生成编码封面报告 coverage/打开 coverage/lcov-report/index.html 在浏览器中显示逐行的详细视图.

大楼

npm run build

编译类型脚本源入 src/ 到 Java 脚本在 dist/,包括类型声明文件(.d.ts) (中文(简体) ). 这个 prebuild 步骤自动清理 dist/ 先说 在发布前运行此功能 .

扶养管理

npm run update-deps

检查所有依赖关系的最新版本并交互升级 package.json,然后安装更新的软件包。 电源 npm-check-updates (单位:千美元)ncu) (中文(简体) ). 运行后的审查和测试——主要版本的起伏可能包含断裂变化.

许可证

这个项目根据麻省理工学院的许可发布. 见 自由主义 详细情况.