检测 App Store 应用更新

苹果官方有一个叫 itunes search api 的东西，可以查询任意 app 的信息，如果一款应用只在某些国家或地区上线，则需要加上国家信息，如果不加默认就是 us。这个接口支持的各种参数可以看苹果官方的说明，文档显示 search api 的请求频率限制在每分钟 20？但是实际好像不止。

The Search API is limited to approximately 20 calls per minute

注意这个 API 不支持查询 app bundle 的信息，例如：

const url =
  "https://apps.apple.com/app-bundle/microsoft-365-mobile-apps/id1564009682";

可以在一个链接中同时请求多个 app 的信息：

const ids = "461703208,414478124";
const api = `https://itunes.apple.com/lookup?id=${ids}&country=cn&output=json&now=kdjai00988fda&lang=zh_cn`;

当 media 为 software 时，entity 参数可以是：software、iPadSoftware 、desktopSoftware，测试发现 tvSoftware、watchSoftware 也可以。关于查询 mac 应用，旧的文档用的是 macSoftware，后来这个 macSoftware 变得不是很准确，所以现在主要用 desktopSoftware。

desktopSoftware delivers metadata for mac-native software. macSoftware seems to be more broad, also includes Catalyst and iOS-only software. The former however is more accurate, as macSoftware might return iPad metadata for certain apps. We therefore prefer desktopSoftware and fall back to macSoftware if no info was found. 出处

entity 之所以重要，是因为 universal purchase。通用购买是 2020 年 3 月上线的，它允许开发者把一个应用在 iphone、mac、tv 等多个平台的版本邦定到同一个 App Store ID 或 Bundle ID 之下。当使用 lookup api 依据这两个 id 查询应用信息时，默认只会获得某个平台（通常是 iOS）的版本信息，而无法获得其他平台（例如 macOS）的版本信息，而通过 entity 则可以获得指定平台的信息。

根据文档，采用通用购买的应用所绑定的应用无法解绑，只能添加。另外，通用购买的应用，如果它支持 iPhone 就肯定支持 iPad，反过来也是，所以 iPhone、iPad 的版本号肯定是相同的，而 Apple Watch 版本不能是 Watch-only 应用，必须和 iOS 版本关联，这意味着 Watch 版本的升级是依赖于 iOS 的。但 Mac 和 TV 版本的版本号可以和 iPhone、iPad 的不同，这时我们可以用 entity 去单独获取这两个版本的信息。在通用购买下，iphone/ipad/watch、mac、tv 这三个版本号各不相同是常见现象。

提供错误的参数，api 会返回报错，如下所示。正如前面说的，文档虽然没有说 entity 可以是 tvSoftware、watchSoftware，但测试发现传入这两个值不会返回报错。通用购买可以添加 visionOS 应用，例如 Infuse，但是 entity 设置为 visionSoftware 会报错。

{
  "errorMessage": "Invalid value(s) for key(s): [country]",
  "queryParameters": {
    "output": "json",
    "callback": "A javascript function to handle your search results",
    "country": "ISO-2A country code",
    "limit": "The number of search results to return",
    "term": "A search string",
    "lang": "ISO-2A language code"
  }
}

需要注意的是，lookup api 可能有延迟，stackoverflow 有人说延迟可能长达 24 小时，下面是原话。为了解决这个问题，可以在 url 后增加一个随机参数，例如当前时间戳。

"In general, there is a 24 hours delay for updated app information to go from App Store Connect to the public."

在 github 一个叫 parse-tunes 的项目可以找到一个和 lookup api 类似的 api。

一些用来测试的应用：

const apps = [
  {
    id: "1660917007",
    name: "Alplayer",
    country: "CN",
    des: "只在 TV",
  },
  {
    id: "424389933",
    name: "Final Cut Pro",
    country: "CN",
    des: "只在 Mac",
  },
  {
    id: "1668598115",
    name: "WorkWork Watch",
    country: "US",
    des: "只在 Watch",
  },
  {
    id: "1018784575",
    name: "Adobe Illustrator: Graphic Art",
    country: "US",
    des: "只在 iPad",
  },
  {
    id: "1069511734",
    name: "Apple Watch",
    country: "CN",
    des: "只在 iPhone",
  },
  {
    id: "461703208",
    name: "高德地图",
    country: "CN",
    des: "Mac、iPhone 版本号不同",
  },
  {
    id: "1630403500",
    name: "APTV",
    country: "CN",
    des: "20241102：mac、iphone/ipad/watch、tv 三个版本号各不相同",
  },
];