操作指南
创建用于定价的 App Store Connect API 密钥
任何代表你修改价格的工具,无论是你自己的脚本还是 RepriceCat,都使用 App Store Connect API 密钥进行身份验证。下面介绍如何创建一个刚好够用、权限不多不少的密钥。
简短回答
在 App Store Connect 中,前往“用户和访问 → 集成 → App Store Connect API → 团队密钥”,生成一个具有 App 管理角色的密钥(如果还想读取销售报告,则用管理员)。下载 .p8 文件——只有一次机会——并复制 Key ID 和 Issuer ID。这三个值就是凭证。
分步创建密钥
Apple 的步骤(Apple:创建 API 密钥)需要管理员账户;如果你的团队从未使用过该 API,则必须先由账户持有人申请访问权限。
- 登录 App Store Connect,打开“用户和访问”,选择“集成”标签页。
- 在左侧栏选择“App Store Connect API”,并确认选中的是“团队密钥”标签页。
- 点击“生成 API 密钥”,或点击添加按钮 (+)。
- 输入一个日后便于识别的名称,例如“Pricing — RepriceCat”。名称仅供你自己参考。
- 在“访问”下选择角色(见下表),然后点击“生成”。
- 点击新密钥旁的“下载 API 密钥”。私钥只会下载一次,是一个 .p8 文件,文件名通常形如
AuthKey_2X9R4HXF34.p8;Apple 不保留副本,下载后链接就会消失。 - 从“有效密钥”列表中复制 Key ID,并复制页面顶部附近显示的 Issuer ID。
| 值 | 样子 | 在哪里找到 |
|---|---|---|
| Issuer ID | 一个 UUID,例如 57246542-96fe-1a63-e053-0824d011072a | App Store Connect API 页面顶部;每个团队密钥都相同 |
| Key ID | 10 个字符,例如 2X9R4HXF34 | “有效”列表中密钥的旁边 |
| 私钥 | 一个以 -----BEGIN PRIVATE KEY----- 开头的 .p8 文本文件 | 你的下载文件;无法再次下载 |
这些示例是 Apple 在其令牌文档中提供的示例值。
密钥应该使用哪个角色?
团队密钥的角色决定了它能做什么,并且无论角色如何,团队密钥都可以访问所有 App。Apple 的定价帮助页面把账户持有人、管理员或 App 管理列为修改 App、App 内购买项目和订阅价格所需的角色(Apple:设置价格、Apple:角色权限)。
| 角色 | 可修改价格 | 销售与趋势报告 | 用于定价? |
|---|---|---|---|
| App 管理 | 是 | Apple 未说明该角色的相关权限 | 是——能管理定价的最小角色 |
| 管理员 | 是 | 是 | 是,如果同一个密钥还要读取销售报告 |
| 财务 | 否 | 是 | 否——仅限报告 |
| 销售 | 否 | 是 | 否——仅限报告 |
| 开发者、市场营销、客户支持 | 否 | Apple 未说明 | 否 |
管理员密钥的权限很大——Apple 指出它们可以创建和删除用户——所以除非需要用同一个密钥读取销售数据,否则请使用 App 管理。按国家或地区读取销售数据见供应商编号与销售报告指南。
团队密钥与个人密钥
App Store Connect 两种都提供。定价请使用团队密钥:
- 团队密钥有明确的角色,创建者离开团队后它依然有效。
- 个人密钥承载某一位用户的访问权限和角色,从该用户的个人资料中生成——前提是管理员已授予“生成个人 API 密钥”的权限。
- 个人密钥无法使用销售与财务端点、配置或 notarytool,因此不适合用于销售报告。
在依赖之前先测试密钥
- 签发 JWT:头部
alg为ES256,kid为 Key ID;载荷中iss为 Issuer ID,iat为当前时间,exp不超过 20 分钟之后,aud为appstoreconnect-v1。 - 用该令牌作为承载头调用
GET https://api.appstoreconnect.apple.com/v1/apps。返回你的 App 列表,就说明密钥可用。 - 401 通常意味着 Issuer ID 或 Key ID 有误、令牌由另一个密钥签发,或令牌有效期过长或已过期(请检查你的系统时钟)。
- 定价调用返回 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 密钥交给定价工具安全吗?
只有在你信任它如何存储密钥时才安全,因为密钥可以做其角色允许的一切。请使用专用的团队密钥,选用可行的最小角色,并在不再使用该工具时撤销它。