跳到内容

操作指南

创建用于定价的 App Store Connect API 密钥

任何代表你修改价格的工具,无论是你自己的脚本还是 RepriceCat,都使用 App Store Connect API 密钥进行身份验证。下面介绍如何创建一个刚好够用、权限不多不少的密钥。

更新于 阅读约需 7 分钟

简短回答

在 App Store Connect 中,前往“用户和访问 → 集成 → App Store Connect API → 团队密钥”,生成一个具有 App 管理角色的密钥(如果还想读取销售报告,则用管理员)。下载 .p8 文件——只有一次机会——并复制 Key ID 和 Issuer ID。这三个值就是凭证。

分步创建密钥

Apple 的步骤(Apple:创建 API 密钥)需要管理员账户;如果你的团队从未使用过该 API,则必须先由账户持有人申请访问权限。

  1. 登录 App Store Connect,打开“用户和访问”,选择“集成”标签页。
  2. 在左侧栏选择“App Store Connect API”,并确认选中的是“团队密钥”标签页。
  3. 点击“生成 API 密钥”,或点击添加按钮 (+)。
  4. 输入一个日后便于识别的名称,例如“Pricing — RepriceCat”。名称仅供你自己参考。
  5. 在“访问”下选择角色(见下表),然后点击“生成”。
  6. 点击新密钥旁的“下载 API 密钥”。私钥只会下载一次,是一个 .p8 文件,文件名通常形如 AuthKey_2X9R4HXF34.p8;Apple 不保留副本,下载后链接就会消失。
  7. 从“有效密钥”列表中复制 Key ID,并复制页面顶部附近显示的 Issuer ID。
值样子在哪里找到
Issuer ID一个 UUID,例如 57246542-96fe-1a63-e053-0824d011072aApp Store Connect API 页面顶部;每个团队密钥都相同
Key ID10 个字符,例如 2X9R4HXF34“有效”列表中密钥的旁边
私钥一个以 -----BEGIN PRIVATE KEY----- 开头的 .p8 文本文件你的下载文件;无法再次下载

这些示例是 Apple 在其令牌文档中提供的示例值。

密钥应该使用哪个角色?

团队密钥的角色决定了它能做什么,并且无论角色如何,团队密钥都可以访问所有 App。Apple 的定价帮助页面把账户持有人、管理员或 App 管理列为修改 App、App 内购买项目和订阅价格所需的角色(Apple:设置价格、Apple:角色权限)。

角色可修改价格销售与趋势报告用于定价?
App 管理是Apple 未说明该角色的相关权限是——能管理定价的最小角色
管理员是是是,如果同一个密钥还要读取销售报告
财务否是否——仅限报告
销售否是否——仅限报告
开发者、市场营销、客户支持否Apple 未说明否

管理员密钥的权限很大——Apple 指出它们可以创建和删除用户——所以除非需要用同一个密钥读取销售数据,否则请使用 App 管理。按国家或地区读取销售数据见供应商编号与销售报告指南。

团队密钥与个人密钥

App Store Connect 两种都提供。定价请使用团队密钥:

  • 团队密钥有明确的角色,创建者离开团队后它依然有效。
  • 个人密钥承载某一位用户的访问权限和角色,从该用户的个人资料中生成——前提是管理员已授予“生成个人 API 密钥”的权限。
  • 个人密钥无法使用销售与财务端点、配置或 notarytool,因此不适合用于销售报告。

在依赖之前先测试密钥

  1. 签发 JWT:头部 alg 为 ES256,kid 为 Key ID;载荷中 iss 为 Issuer ID,iat 为当前时间,exp 不超过 20 分钟之后,aud 为 appstoreconnect-v1。
  2. 用该令牌作为承载头调用 GET https://api.appstoreconnect.apple.com/v1/apps。返回你的 App 列表,就说明密钥可用。
  3. 401 通常意味着 Issuer ID 或 Key ID 有误、令牌由另一个密钥签发,或令牌有效期过长或已过期(请检查你的系统时钟)。
  4. 定价调用返回 403,通常意味着该密钥的角色无法管理价格——请使用具有 App 管理或管理员角色的密钥。

一切正常之后,定价 API 指南会介绍价格点和价格计划端点。

安全保存

  • 把 .p8 当作密码对待。拥有它和那两个 ID 的人,可以用该密钥的角色对团队的每个 App 执行操作。
  • Apple 的建议:不要共享密钥,不要把它们存放在代码仓库中,也不要包含在客户端代码里。
  • 一个用途一个密钥。定价密钥不必是 CI 用来上传的密钥,这样撤销其中一个不会影响另一个。
  • 如果要把它粘贴到某个工具中,请先确认该工具会如何处理它。RepriceCat 在存储之前会用 AES-256-GCM 加密密钥,绝不会把它送回浏览器,并且只用它为你自己的账户签发短期令牌。

常见错误

  • 因为“听起来更安全”而选择开发者或市场营销角色。这样密钥可以读取数据,但每次修改价格都会失败。
  • 从个人资料创建了个人密钥,之后却不明白为什么销售报告被拒绝——个人密钥无法使用销售与财务端点。
  • 混淆 Key ID 和 Issuer ID。Key ID 较短,作为 kid 放在令牌头部;Issuer ID 是较长的 UUID,作为 iss 放在载荷中。
  • 签发有效期超过 20 分钟的令牌。Apple 对定价端点会拒绝这类令牌;耗时较长的任务应定期签发新令牌,并在每个令牌过期前复用它。
  • 把 .p8 文件提交到代码仓库,哪怕是私有仓库。应把它移到密钥存储中,并撤销已暴露的密钥。
  • 让 CI 上传、定价脚本和第三方工具共用一个密钥。因某个原因撤销它时,其他一切也会随之失效。

还在考虑是用这个密钥自己写定价脚本,还是使用现成工具?RepriceCat 与 API 脚本对比列出了各自的取舍。

撤销密钥

当有人离开、密钥可能已泄露,或者你不再使用某个工具时,就应撤销密钥。管理员可以在“用户和访问”的 API 密钥列表中撤销团队密钥(Apple:撤销 API 密钥)。撤销是永久的:被撤销的密钥无法恢复,所有用它签发的令牌都会失效,它会在“已撤销”下保留 30 天。如果你丢失了 .p8,请撤销该密钥并生成新的。

在 RepriceCat 中使用密钥

连接 RepriceCat 需要具有 App 管理或管理员角色的团队密钥的 Issuer ID、Key ID 和 .p8 文件。此后:

  • 密钥在静态存储时是加密的,你可以随时在 App Store Connect 中撤销它。
  • 在你批准对每个产品和国家或地区的审核之前,不会向 Apple 发送任何内容;试运行也不会发送任何内容。
  • 销售页面另外需要你的供应商编号,以及具有管理员、财务或销售角色的密钥——所以一个管理员密钥就能同时覆盖定价和销售。

准备好了吗?连接密钥并为你的第一个 App 调价——第一个月免费,之后每个 App 每月 $1。

常见问题

在哪里找到 Issuer ID?

在 App Store Connect 的“用户和访问”→“集成”→“App Store Connect API”下。它靠近页面顶部,旁边有“拷贝”按钮,并且账户上的每个团队密钥都相同。

我丢了 .p8 文件,还能再下载吗?

不能。Apple 只允许下载一次私钥,并且不保留副本。请撤销该密钥并生成新的。

哪个 App Store Connect 角色可以修改价格?

管理员和 App 管理,以及账户持有人。App 管理是能管理定价的最小角色;开发者、市场营销、财务和销售不行。

谁可以创建 App Store Connect API 密钥?

团队密钥由拥有管理员账户的人生成,前提是账户持有人已为团队申请了 API 访问权限。个人密钥则在管理员授予该权限的情况下,从用户自己的个人资料中生成。

可以用个人 API 密钥来定价吗?

如果该用户自己的角色允许定价,就可以用于修改价格,但团队密钥是更好的选择:它有明确的角色,用户离开后依然有效。个人密钥也无法访问销售与财务报告。

把 API 密钥交给定价工具安全吗?

只有在你信任它如何存储密钥时才安全,因为密钥可以做其角色允许的一切。请使用专用的团队密钥,选用可行的最小角色,并在不再使用该工具时撤销它。

试一试

从一个基准价格为每个国家/地区重新定价

价格档、自动对齐价格点、一张检查表、一次确认,全部通过 App Store Connect API 完成。首月免费,之后每个 App 每月 $1。