開源一款蘋果 macOS 工具 - AppleParty（蘋果派）

AppleParty 是 37手游 iOS 團隊研發，實現快速操作 App Store Connect 后台的自動化 macOS 工具。本文會介紹工具誕生的背景、使用教程和代碼實現的簡介，希望通過開源與大家分享成果，讓更多人一起參與改進和完善，最后一起提高效率和拓展探索方向。

一、前言

大家好，很高興告訴大家一件重要的事情，我們發起了一個開源項目 —— AppleParty（蘋果派）（蘋果派）。這是我們團隊在上一個 開源的 App Store 后又一個嘗試。AppleParty 這個項目是我們 37手游 iOS 團隊內部孵化的一個產品，希望這個項目能作為一個引子，通過開源與大家分享成果，一起提高效率和拓展大家對未來的探索方向。

二、項目背景

目前，iOS/macOS App 上架 App Store，與蘋果打交道的唯一方式，就是登陸蘋果 App Store Connect 后台（https://appstoreconnect.apple.com，通過蘋果后台進行 App 所有的信息和素材等送審准備工作。但是，目前蘋果后台的自動化水平還處於零基礎，很多重復的操作和功能，都沒有提供批量處理方案，比如：

• 商店截圖和預覽視頻的上傳
• 應用內購商品的創建和更新
• App 本地化的元數據信息配置
• 開發者證書創建和管理
• ...

App 分析的指標：

• 展示次數
• 產品頁面查看次數
• 首次下載次數
• 凈預訂量
• 平台版本（iOS14.5、iOS15...)
• 頁面類型（產品頁面、商店表單、App內活動...）
• 用戶來源（網頁引薦來源、App 引薦來源、AppStore 瀏覽、AppStore 搜索、活動通知...）
• ...

以上的 App 分析數據，每次只能下載一個指標的數據，每個 App 有十幾個指標，操作這些重復的配置往往占用了運營同學非常長的時間，效率低且重復無聊的工作，導致我們長期無法做更多的時間開啟和享受創造性。

基於以上種種痛點，我們從多個技術手段，打造了 Apple Party（蘋果派對）工具! 通過盡可能快速實現操作的自動化流程，從而大大提高蘋果后台的操作效率！

注：目前蘋果有提供 App Store Connect API 方式，但是目前迭代的功能，還不能滿足所有的需求，下文會展開說明。

2.1 Apple Party（蘋果派）名字起源

Apple Party（蘋果派）

我們倡導工作之余，豐富多彩的生活要領，健身、旅游、聚會、培養藝術興趣等等。

• Party：派對 即 “宴會，聚會” 的意思，大家聚在一起慶祝和休閑的一種活動。

所以，Apple Party（蘋果派對），簡稱：蘋果派，就是希望大家在使用蘋果的服務時，像似參加一場蘋果派對，盡情歡樂，歡聚宴會~

我們希望，大家在 AppleOS 生態下開發時，可以提高效率，專注於核心內容，然后愉快派對！

三、使用說明

3.1 注意事件

目前實現的功能

• 內購買項目管理（批量創建和更新）；
• 批量商店圖和預覽視頻上傳和更新；
• 數據報表批量下載(后續開源)；
• 郵件發送工具；
• 二維碼掃描和生成工具；

注：內購買項目和商店素材上傳，暫時只支持 iOS app，未來會考慮支持 macOS app、tvOS app。

環境依賴

• 支持 macOS 10.13 和以上系統
• 依賴 Transporter.app
• 依賴 Xcode（Transporter.app 依賴）

3.1 安裝包下載

目前我們在 GitHub 開源 37iOS/AppleParty，所以提供GitHub 安裝包：

• AppleParty 下載

update 更新

目前已經使用 Sparkle 來實現版本更新，默認啟動就會自動檢查更新，也可以通過菜單欄進行手動檢查更新。

3.2 使用介紹

因為賬號記錄是存放在 Keychain 里，所以首次打開時，會提示需要訪問鑰匙串：

如果點擊“拒絕”，則不會保存賬號和密碼信息。

然后，會顯示主界面：

默認情況下彈出登陸界面，也可以點擊取消登陸（快捷鍵esc）：

現在默認登陸都需要雙重認證：

如果需要使用短信驗證碼，可以點擊“發送短信驗證碼”，如果希望通過語言驗證碼，可以勾選“撥打語言來電”切換：

3.2.1 批量上傳內購買項目和商店素材

點擊“我的 App”，顯示帳號所有的App，可以操作內購買項目管理和商店素材管理。

點擊內購管理，顯示當前已有的內購品項列表:

• 刷新：刷新當前App的內購品項列表（剛剛上傳的品項不會馬上生效，所以可以手動刷新）
• 導入表格：通過固定表格的形式，批量創建內購品項
• 導出表格：導出所有品項的信息 Excel 表
• 導出品項 ID：導出品項productID和內購品項id的對應表
• 下載表格示例：批量創建內購品項的示例 Excel 表格

點擊 “導入表格”，可選擇excel表進行導入，然后會顯示導入的品項明細表。

如上圖所示，列表1和2是自定義的送審截圖，所以需要點擊右下角的“上傳截圖”選定。

“提交”后，會顯示下面的界面，如未設置專用密碼，首次需要設置，或者點擊右下角“設置特殊密碼”重新設置。

專用密碼的生成參考文檔：使用 App 專用密碼 - Apple 支持 (中國)

上傳失敗時，查看 ERROR 內容就是錯誤內容：

批量素材上傳

點擊“素材一鍵導入”一鍵上傳，素材可以分別在不同尺寸下顯示。

對應的尺寸，上傳視頻和截圖后，填寫排序的位置和視頻海報幀：

可點擊右上角 ？按鈕查看幫助文檔。

3.2.2 其它擴展功能

郵箱功能，一方面是可以設置快速郵件發送，另一方面是工具效率自動郵箱的通知需求。

二維碼功能也是一個工作中的小痛點。

四、代碼實現簡解

4.1 上傳內購買項目和商店素材

使用的是蘋果提供的 Transporter 工具鏈，提供了上會的命令，有 3 個工具：

• Xcode.app
• Application Loader.app
• Transporter.app

其中，Application Loader 已經棄用了，可以忽視。Transporter 命令所有的目錄：

Xcode.app:

/Applications/Xcode.app/Contents/SharedFrameworks/ContentDeliveryServices.framework/Versions/A/itms/bin/iTMSTransporter

Transporter.app:

/Applications/Transporter.app/Contents/itms/bin/iTMSTransporter

4.1.1 Transporter 命令使用

Lookup Metadata 模式

獲取 app 信息，獲取到一個 xxx.itmsp 包，里面有關於 app 版本和內購品項等信息的 xml 格式文件。

iTMSTransporter -m lookupMetadata -u [user] -p [password] -apple_id(-apple_ids) -destination [output_path]

示例：

同時獲取多個 app 信息：

iTMSTransporter -m lookupMetadata -u [e-mail] -p 專用密碼 -apple_ids 10 xxxx,多個appid,xxx -destination /Users/37/Desktop/output

獲取單個 app 信息：

iTMSTransporter -m lookupMetadata -u 賬號郵箱 -p 專用密碼 -apple_id 某個appid -destination /Users/37/Desktop/output

Provider 模式

查詢供應商，也就是開發者賬號的名字和團隊 id：

iTMSTransporter -m provider -u [user] -p [password]

示例：

iTMSTransporter -m provider -u [e-mail] -p 專用密碼

輸出內容：

Provider listing:
   - Long Name -         - Short Name -
1  apple_dev           	  28PV6...4
2  37iOSTeam              R7S9...R1

Verify 模式
校驗上傳內容是否合法。

iTMSTransporter -m verify -u [user] -p [password] -f [itmsp_path] [-vp ]

示例：

iTMSTransporter -m verify -u [e-mail] -p 專用密碼 -f /Users/37/Desktop/IAP.itmsp

Upload 模式
上傳內容。

iTMSTransporter -m upload -u [user] -p [password] -f [itmsp_path]

示例：

iTMSTransporter -m upload -u [e-mail] -p 專用密碼 -f /Users/37/Desktop/IAP.itmsp

一些重要參數說明：

• -itc_provider: 檢查和上傳時建議加子賬號的團隊id，但測試發現不用也行，先不帶，因為獲取很麻煩
• -errorLogs: 存儲錯誤日志的目錄
• -loghistory: 記錄成功上傳的數據包
• -outputFormat xml: 以 XML 格式返回輸出信息,
• -throughput: 顯示成功上傳數據包的總傳輸時間以及數據包大小和每秒字節數
• -o: 記錄輸出信息
• -v: 日志級別，默認 eXtreme，詳細
• -vp: 在驗證或上傳數據包文件時顯示進度信息
• -Xmx4096m: 指定 4 GB Java 虛擬機 (JVM) 堆棧內存

詳細，可以參考：指定選項和值 - Transporter

詳細也可以查看官方文檔：

• What is Transporter?
• Transporter 用戶指南 2.0
• Transporter 幫助
• App 元數據規范 5.11

4.1.2 itmsp 數據包說明

通過命令，可以了解到，我們需要組裝一個 .itmsp 的文件夾，里面包含我們需要上傳的內購買項目的信息，送審截圖，或者商店圖片和預覽視頻等。

內購買項目的 xml 配置文件

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://apple.com/itunes/importer" version="software5.9">
    <provider>{team_id}</provider>
    <software>
        <vendor_id>{SKU}</vendor_id>
        <software_metadata>
            <in_app_purchases>
                <in_app_purchase>
                    <!-- 可以由字母、數字、下划線（_）和句點（.）構成，最多 255 個字符 -->
                    <product_id>com.app.1usd</product_id>
                    <reference_name>1ud（2~64 個字符）</reference_name>
                    <!-- 消耗型項目consumable 非消耗型non-consumable 自動續期訂閱auto-renewable 非續期訂閱subscription -->
                    <type>consumable</type>
                    <products>
                        <product>
                            <cleared_for_sale>true</cleared_for_sale>
                            <wholesale_price_tier>3</wholesale_price_tier>
                        </product>
                    </products>
                    <locales>
                        <locale name="en-US">
                            <title>2~30個字符</title>
                            <description>至少10~45個字符</description>
                        </locale>
                        <locale name="zh-Hans">
                            <title>中文2~30個字符</title>
                            <description>至少10~45個字符</description>
                        </locale>
                    </locales>
                    <review_screenshot>
                        <!-- Supported dimensions are: 1334x750, 750x1334, 1024x768, 1024x748, 768x1024, 768x1004, 2048x1536, 2048x1496, 1536x2048, 1536x2008, 2224x1668, 1668x2224, 960x640, 960x600, 640x960, 640x920, 2208x1242, 1242x2208, 2436x1125, 1125x2436, 312x390, 1136x640, 1136x600, 640x1136, 640x1096, 2732x2048, 2048x2732" -->
                        <size>636132</size>
                        <file_name>IMG_5180.PNG</file_name>
                        <checksum type="md5">xxxxx</checksum>
                    </review_screenshot>
                    <review_notes>Some notes for the reviewer.（2~4000字符）</review_notes>
                </in_app_purchase>
            </in_app_purchases>
        </software_metadata>
    </software>
</package>

商店圖片和預覽視頻的 xml 配置文件

<?xml version="1.0" encoding="UTF-8"?>
<package version="software5.10" xmlns="http://apple.com/itunes/importer">
    <provider>{provider}</provider>
    <team_id>{provider}</team_id>
    <software>
        <vendor_id>{vendor_id}</vendor_id>
        <software_metadata app_platform="{app_platform}">
            <versions>
                <version string="{app_version}">
                    <locales>
                        <locale name="{app_locale}">
                            <title>{title}</title>
                            <app_previews>
                                <app_preview display_target="{iOS-5.5-in}" position="{1}">
                                    <data_file role="source">
                                        <size>{video_size}</size>
                                        <file_name>{video_name}</file_name>
                                        <checksum>{video_md5}</checksum>
                                    </data_file>
                                    <preview_image_time format="30/1:1/nonDrop">{00:00:05:00}</preview_image_time>
                                </app_preview>
                            </app_previews>
                            <software_screenshots>
                                <software_screenshot display_target="{iOS-5.5-in}" position="{1}">
                                    <size>{image_size}</size>
                                    <file_name>{image_name}</file_name>
                                    <checksum type="md5">{image_md5}</checksum>
                                </software_screenshot>
                            </software_screenshots>
                        </locale>
                    </locales>
                </version>
            </versions>
        </software_metadata>
    </software>
</package>

上傳 iap 包的 xml 配置文件

<?xml version="1.0" encoding="UTF-8"?>
<package version="software5.10" xmlns="http://apple.com/itunes/importer">
  <software_assets apple_id="{apple_id}" app_platform="ios">
    <asset type="bundle">
      <data_file>
        <size>{file_size}</size>
        <file_name>{file_name}</file_name>
        <checksum type="md5">{file_md5}</checksum>
      </data_file>
    </asset>
  </software_assets>
</package>

詳細的格式，可以參考項目里的示例：https://github.com/37iOS/AppleParty/tree/main/AppleParty/Resources/Transporter。大家有任務疑問，歡迎在評論區留言哈~

4.2 App 分析數據、銷售趨勢

iOS app 發布上線后，用戶從 App Store 搜索和下載 app， 查看 app 產品頁面，下載並且使用過程中，app 的使用次數、內購充值、或者崩潰等數據，還有后續的付款和財務報表等。

這些數據對於游戲運營和財務部門來說，同樣非常的重要。一般是在蘋果后台查看或下載導出，所以希望能從蘋果后台自動化的方式獲取到這些數據。

目前蘋果后台關於數據的功能有這三個：

• App 分析
• 銷售和趨勢
• 付款和財務報告（目前沒有使用）

注：付款和財務報告是 app 內購買的金額統計和對訂單，目前的導出數據需求里，並不需要此數據。

4.2.1 調研報告

通過調研，目前主流的方法有以下三種：

• 蘋果官方：App Store Connect API：REST API，下載銷售和趨勢報告（.txt文件）
• 蘋果官方：Reporter 命令行工具：.jar包，跨平台，下載銷售和趨勢報告（.txt文件）
• 第三方開源：Fastlane - Spaceship：需要Ruby環境，獲取每日銷售明細（json數據）

對應的文檔：

• App Store Connect API | Apple Developer Documentation
• Reporter 用戶指南 3.1.6
• fastlane/spaceship · fastlane

4.2.2 App Store Connect API

自定義工作流程並實現自動化，以便您集中精力打造出色的 app。這個基於標准規范的 REST API 讓您可以跨各種開發者工具 (如 App Store Connect、Xcode 以及“Certificates, Identifiers & Profiles”(證書、標識符和描述文件)) 實現任務自動化，使工作流程更靈活、更高效。這個 API 可用於開發、beta 版測試、管理 app 元數據、生成報告等。

銷售和趨勢
下載報告，以查看您的 app 在所有 Apple 平台上的首次下載量、銷售額、收入、預訂量、訂閱活動等。

付款和財務報告
下載按產品、銷售地區、貨幣、價格等划分的月度收入報告。您可以查看每個月的付費金額，以及任何納稅調整或預扣稅。

URL

GET https://api.appstoreconnect.apple.com/v1/salesReports

具體請求參數和響應，可以查看文檔：Download Sales and Trends Reports | Apple Developer Documentation

4.2.3 Reporter 命令行.

Reporter 是一個命令行工具，可以用來下載您的銷售和趨勢報告以及付款和財務報告。您還可以查看錯誤說明以及延遲報告的預計可用時間等信息。如果您的多個開發者帳戶使用同一個 Apple ID，您可以在 Reporter 輕松切換帳戶。

下載銷售和趨勢報告
使用 Sales.getReport 命令下載銷售和趨勢報告。

下載財務報告
使用 Finance.getReport 命令可為您下載財務報告。

語法

$ java -jar Reporter.jar p=[properties file] Sales.getReport [vendor number], [report type], [report subtype], [date type], [date], [version]*（如適用）

具體請求參數和響應，可以查看文檔：下載銷售和趨勢報告 - Reporter 用戶指南 3.1.6

4.2.4 Spaceship

spaceship exposes both the Apple Developer Center and the App Store Connect API. It’s super fast, well tested and supports all of the operations you can do via the browser. It powers parts of fastlane, and can be leveraged for more advanced fastlane features. Scripting your Developer Center workflow has never been easier!

spaceship 公開了 Apple Developer Center 和 App Store Connect API。它速度超快，經過充分測試並支持您可以通過瀏覽器執行的所有操作。它為 fastlane 的部分功能提供支持，並可用於更高級的 fastlane 功能。編寫您的開發人員中心工作流程腳本從未如此簡單！

相當於第三方對蘋果接口的封裝，並且是依賴 Ruby 環境執行，對於我們的自動化來說，可以使用。但是，如果是工具化，那么並不適用，所以，不作深入研究。大家有興趣可以看看：spaceship · fastlane/fastlane。

4.2.5 爬蟲

以上介紹的3種方式都不支持獲取和下載App 分析數據，所以，從目前技術方案來說，爬蟲是實現方案中成本和可行性最低的方法。

爬蟲的原理：模擬開發者輸入賬號密碼（獲取到用戶的登陸狀態），然后點擊登陸，點擊對應的頁面標簽，下載對應的數據。

方案

• 用 python 爬蟲庫
• 用 Swift 網絡庫

4.2.6 總結

方案	優點	缺點	登陸驗證方式	自動化程度
App Store Connect API	官方維護，接口和文檔全	不支持下載App 分析數據	API keys	高
Reporter 命令行工具	官方維護，接口和文檔全	不支持下載App 分析數據	訪問令牌	高
Fastlane - Spaceship	命令自動化工具	不支持下載App 分析數據	API keys、賬密(+驗證碼)	中
爬蟲	蘋果后台所有功能都支持	如果接口變更， 開發者也需要調整	賬密(+驗證碼)	中

綜上，從目前業務場景和業務需求來說，爬蟲是當前折中的方案，也是最快和最有效的方案。未來，如果蘋果 App Store Connect API 或 Reporter 工具 支持下載App 分析數據，那么，這將是更好的方案，讓我們一起期待 WWDC 2022 吧！

最后

AppleParty 要解決的問題是開發者有很多 app 的情況下的管理，比如有多語言、頻繁更新等，當然也有針對游戲行業的需求，比如素材會經常更新，內購買項目達到100+個，人工處理顯示無法滿足。而為什么不考慮做成命令行的工具？因為希望相關的這塊工具可以交給運營處理，而不需要技術關注。

大家可能有一個疑問：為什么不使用 SwiftUI？因為考慮工具的通用性，兼容更多的系統版本，顯然才是工具要做的事情，所以，相信未來一定會用上 SwiftUI 的！另外，蘋果為什么不推出批量操作和更加完善的工具呢？很顯然，蘋果在努力打造 App Store Connect API，但其實蘋果的功能非常多，一步到位解決所有的問題不太現實，所以，我們也非常期待蘋果新的 API，來解決更多重復操作的問題。

以上就是 AppleParty 項目的內容簡單介紹，大家可以在 GitHub 37iOS/AppleParty 查看詳細的源代碼。如果覺得不錯，給我們點個贊！如有疑問或者問題，歡迎留言交流~

最后，Apple Party（蘋果派）是一個新生孩，所以可能會存在很多缺陷，甚至不能滿足所有的場景，希望大家多擔待和理解萬歲，期待大家一起給項目提建議，提代碼，一起卷好！

歡迎關注我們，了解更多 iOS 和 Apple 的資訊~

特別感謝

• Alamofire/Alamofire
• Kitura/Swift-SMTP
• SnapKit/SnapKit
• sparkle-project/Sparkle
• tid-kijyun/Kanna
• drmohundro/SWXMLHash
• jdg/MBProgressHUD
• joshuajylin/MBProgressHUD-macOS
• Yueoaix/SymbolicatorX
• fpotter/ExpandingDatePicker
• kishikawakatsumi/KeychainAccess

參考引用

• 37iOS/AppleParty: macOS App for App Store Connect to Improve Processing Efficiency and Enjoy the Party.
• 用 SwiftUI 實現一個開源的 App Store - 掘金
• Apple Transporter.app
• 使用 App 專用密碼 - Apple 支持 (中國)
• What is Transporter?
• Transporter 用戶指南 2.0
• Transporter 幫助
• App 元數據規范 5.11
• App Store Connect API | Apple Developer Documentation
• Reporter 用戶指南 3.1.6
• 下載銷售和趨勢報告 - Reporter 用戶指南 3.1.6
• fastlane/spaceship · fastlane
• Download Sales and Trends Reports | Apple Developer Documentation