高级

創建通知群組¶

您可以在通知中心以群組的形式顯示通知。對應於同一事件的通知可以被分組並以摺疊的形式顯示。用戶可以再次展開摺疊的通知群組，並且可以單獨執行每個屬於該群組的通知。

通過將群組鍵更改為啟用並在控制台 > 通知 > 推送 v4 > 註冊推送活動 > 活動註冊 > 選項 > 群組鍵中添加鍵值，可以創建通知群組。在控制台中創建群組後，您可以在發送本地推送和遠程推送通知時使用groupId應用通知群組。當應用群組時，通知將按群組以摺疊形式顯示，如下所示。

安卓	iOS

</tbody>

iOS 媒體通知¶

透過利用 Apple 的 UserNotifications 框架，您可以將媒體文件，例如圖片和視頻，添加到通知中。

JPG（圖片）	GIF（圖片）	MP4（視頻）

操作流程¶

媒體通知功能使用 iOS 的 通知服務擴展（以下簡稱為擴展）。

通知服務擴展是一種應用擴展，允許您在遠程通知發送給用戶之前修改有效載荷，使您能夠在不切換上下文的情況下使用其他應用的過程（UI或功能）。有關更多詳細信息，請參閱更多。

• 應用擴展後發送遠程通知的過程

檔案大小和類型限制¶

附加媒體檔案時有大小限制，詳細資訊可以在UNNotificationAttachment中找到。

• 如果因為網絡條件不佳而發生超時，使用者將收到一個沒有媒體的常規通知。
• 在非常慢的網絡上，下載可能需要長達10分鐘，因此有必要考慮該地區的網絡條件，並使用適當大小的媒體。

實施與利用¶

要下載媒體並重建通知對象以便發送給用戶，需要幾個設置和額外的源代碼。

添加擴展¶

要使用媒體通知功能，您需要在項目中添加通知服務擴展。不要直接添加或覆蓋類，而是向項目添加一個新目標。

當您添加目標時，會自動創建一個模板。

在 Unity 專案中新增目標¶

Unity 編輯器中，Hive SDK 會透過 PostProcess 功能自動執行新增目標與撰寫 Info.plist 等一系列流程。只要勾選是否使用媒體推播即可，無需其他作業。

1. 在 Unity 編輯器上方選單列中，進入 Hive > Build project post process settings > iOS 選單
2. 啟用 Push Media Contents

在 Unity 以外環境中新增目標¶

開始前請先確認以下項目。

• 若要使用推播擴充目標，請確認佈建描述檔中已包含 aps-environment 權限（entitlement）。如有需要，請重新簽發佈建描述檔與憑證。
• 若以 Xcode GUI 直接新增目標，擴充目標的最低支援版本預設可能會設為最新 OS。請確認此值未超過主遊戲 App 目標的最低支援版本。

目標新增方式如下。

1. 在 Xcode 專案設定中，點擊 新增目標 按鈕（左下角 + 按鈕）
2. 選擇 Notification Service Extension 後，點擊 Next
   （自 Xcode 8 起可在專案中將 Notification Service Extension 新增為目標）
3. 輸入 Product Name
4. 出現如下彈出視窗時，點擊 Activate
   目前專案會自動包含（Embedded）Extension，並新增用於建置的 Scheme
5. 在 General 分頁中確認專案已新增 Extension
6. 確認專案已新增 NotificationService 範本類別

添加 HIVEExtensions.framework¶

您可以使用Hive提供的HIVEExtensions.framework轻松下载媒体。

添加 HIVEExtensions.framework 的方法如下：

1. Hive SDK 支持 CocoaPods。如果您的项目目录中没有 Podfile，请运行 pod init。

   

   如果您已經有一個 Podfile，請打開該文件並添加目標 'NotificationServiceExtension (示例目標名稱)' do-end 語句。

2. 請參考截圖並撰寫 pod 聲明。

3. 關閉 Podfile，並在您的專案目錄中運行 pod install。

4. 當你打開 NotificationSample (範例專案名稱).xcworkspace 時，你會看到 Pods 專案已經如下面所示添加。現在你可以在 NotificationSample 和 NotificationServiceExtension 目標中導入 HIVEExtensions。

應用框架¶

在 NotificationService.swift 文件中導入框架，如示例所示。 實現模板中提供的方法，以調用 HIVEExtensions.framework 提供的方法並刪除方法內部的原始模板代碼。

import HIVEExtensions

func didReceiveNotificationRequest(request: UNNotificationRequest, with contentHandler: (UNNotificationContent) -> Void) {
    HIVENotificationService.didReceive(request) { content in
        guard let content else { return }
        contentHandler(content)
    }
}

func serviceExtensionTimeWillExpire() {
    HIVENotificationService.serviceExtensionTimeWillExpire()
}

#import <HIVEExtensions/HIVEExtensions.h>

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
[HIVENotificationService didReceiveNotificationRequest:request withContentHandler:contentHandler];
}

- (void)serviceExtensionTimeWillExpire {
[HIVENotificationService serviceExtensionTimeWillExpire];
}

申請注意事項¶

發送和接收時間的差異¶

在擴展中的所有任務完成後，通知會發送給用戶，這可能導致發送時間和接收時間之間的差異，客戶端將根據伺服器發送的時間顯示時間。

例如，如果在15:00發送通知，而下載在15:05完成，則該通知將顯示為在15:00到達。

設備容量¶

透過推播通知接收的媒體會儲存在使用者的裝置上，然後透過推播進行顯示，而接收到的媒體則儲存在裝置的內部快取資料空間中，佔用使用者裝置的內部容量。如果使用者裝置的內部儲存容量不足，快取資料空間會由作業系統自動清除。

使用者的行動數據使用情況¶

透過推播通知接收的媒體將使用用戶的行動數據進行下載，且下載將在未經用戶同意的情況下進行，這可能在下載過程中產生數據使用費用。

在透過推送交付音頻/視頻文件的情況下，請在下載之前檢查用戶的網絡連接狀態。如果用戶未連接到 Wi-Fi，則不要繼續下載，而是顯示一個沒有媒體的推送通知。

此時，通過推送接收到的媒體類型由媒體 URL 末尾指定的擴展名確認，並且只有在[文件大小和類型限制]部分中指定的擴展名才會正確顯示。

應用程式傳輸安全設定¶

蘋果的預設政策允許所有應用程式進行的伺服器通信使用 https，並且通過通知接收到的 URL 也受到此政策的影響。如果您想使用 Http 網域進行通信，則需要設置 App Transport Security (ATS) 例外。
即使應用程式具有 ATS 例外處理，您仍必須在擴展中設置 ATS 例外，以便使用 http 網域來傳輸通過推送通知的 URL。

當媒體未在Unity中交付¶

Hub connection error Error Domain=NSCocoaErrorDomain Code=4097 "connection to service named com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.NotificationServiceExtension" UserInfo={NSDebugDescription=connection to service named com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.NotificationServiceExtension}

在 Unity 中，可能会出现媒体未传递的情况，同时显示如上所示的错误日志。在这种情况下，请检查创建的扩展目标的架构中是否包含 armv7 和 arm64 的值。

推送操作按鈕¶

推送操作按鈕是當您長按推送通知時出現的系統按鈕，如下所示。通過在推送通知中顯示這些額外的按鈕，您可以鼓勵用戶互動。

使用 Hive SDK，您可以輕鬆地通過簡單的配置實現推送操作按鈕。

安卓	iOS

基本實作 (iOS)¶

Hive SDK 提供了一組基於常用模式的預設推播動作按鈕，例如「確認」、「拒絕」等。這些內建的按鈕組合可以快速應用，您也可以根據需要定義和擴展自訂的動作按鈕組。預設的推播動作按鈕組如下所示。

不需要額外的代碼來應用這些推送操作按鈕集，但您必須在項目中添加一個 Notification Content Extension 目標。請參閱下面的「推送操作按鈕集應用指南」，以便在您的開發環境中添加目標並啟用推送操作按鈕。

在 Unity 套用推播動作按鈕組¶

Unity 編輯器中，Hive SDK 的 PostProcess 功能會自動執行新增目標與撰寫 Info.plist 等一系列流程。只需勾選是否使用推播動作按鈕，無需其他作業。

1. 在 Unity 編輯器上方選單列中，進入 Hive > Build project post process settings > iOS 選單。
2. 啟用 Push Action Buttons。

啟用按鈕時顯示的清單，是下方 進階實作方法 中使用的 hive_push_actions.json 檔案內 categories 欄位清單預覽。若未使用該檔案而以基本實作進行，則會顯示為 'none'。

在 Unity 以外環境套用推播動作按鈕組¶

開始前請先確認以下項目。

• 若要使用推播擴充目標，請確認佈建描述檔中已包含 aps-environment 權限（entitlement）。如有需要，請重新簽發佈建描述檔與憑證。
• 若以 Xcode GUI 直接新增目標，擴充目標的最低支援版本預設可能會設為最新 OS。請確認此值未超過主遊戲 App 目標的最低支援版本。

接著，產出 Xcode 專案（.xcodeproj）後，請依下列順序進行。

第 1 階段：新增推播擴充目標¶

請依下列步驟新建擴充目標，並連結至 App 目標。

1. 在 Xcode 專案設定中，按下左下角的 + 按鈕以新增目標。
2. 選擇 Notification Content Extension 後，點擊 Next。
3. 輸入 Product Name，並在 Embed in Application 指定主遊戲 App 目標。
4. 出現下方彈出視窗時，點擊 Activate。目前專案會自動包含（Embedded）Extension，並新增用於建置的 Scheme。
5. 在主遊戲 App 目標的 General > Frameworks, Libraries, and Embedded Content 中，確認已新增上方輸入的 Product Name。

第 2 階段：自動產生檔案自訂¶

請對 Product Name 群組中自動產生的以下 3 個檔案分別執行下列作業。

移除 MainInterface.storyboard¶

移除 Product Name/MainInterface.storyboard。

修改 NotificationViewController.swift¶

修改 Product Name/NotificationViewController.swift。

請將如上自動產生的範本類別檔案內容修改如下。可複製下方程式碼區塊使用，或新增圖片中以橘色標示的行。

import UIKit
import HIVEExtensions
import UserNotifications
import UserNotificationsUI

class NotificationViewController: UIViewController, UNNotificationContentExtension {

    func didReceive(_ notification: UNNotification) {
        HiveNotificationContent.didReceive(notification)
    }

    func didReceive(_ response: UNNotificationResponse) async -> UNNotificationContentExtensionResponseOption {
        await HiveNotificationContent.didReceive(response)
    }

}

修改 Info.plist¶

修改 Product Name/Info.plist。

請依下列順序，將以下程式碼貼到最上層 Information Property List 行（根字典，亦即圖片中以橘色標示的行）之下。

1. 展開最上層 Information Property List 行，移除其下層項目 NSExtension。
2. 收合同一行後按右鍵，選擇 Paste（貼上）。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSExtension</key>
    <dict>
    <key>NSExtensionAttributes</key>
    <dict>
        <key>UNNotificationExtensionInitialContentSizeRatio</key>
        <integer>0</integer>
        <key>UNNotificationExtensionCategory</key>
        <array>
        <string>INFO_CATEGORY</string>
        <string>CLOSE_CATEGORY</string>
        <string>CONFIRM_CATEGORY</string>
        <string>EXECUTE_CATEGORY</string>
        <string>ACCEPT_ALL_CATEGORY</string>
        <string>ACCEPT_NOW_CATEGORY</string>
        <string>PURCHASE_CATEGORY</string>
        <string>SALE_CATEGORY</string>
        <string>ACCEPT_DECISION_CATEGORY</string>
        </array>
    </dict>
    <key>NSExtensionPrincipalClass</key>
    <string>$(PRODUCT_NAME).NotificationViewController</string>
    <key>NSExtensionPointIdentifier</key>
    <string>com.apple.usernotifications.content-extension</string>
    </dict>
</dict>
</plist>

第 3 階段：填寫自訂類別¶

在上一步驟中修改的 Info.plist 內 UNNotificationExtensionCategory 值，是前述 Hive SDK 預設提供的類別。若依下方 進階實作方法 在 hive_push_actions.json 中撰寫了自訂類別，也請一併加入陣列元素。

第 4 階段：新增相依性¶

請連結推播擴充目標所需的相依性。若在專案產出後已透過 CocoaPods 等方式新增，則可略過。

• 使用相依性管理工具新增
  • 使用 CocoaPods 時：請參考 指南，在推播擴充目標中新增 HiveExtensions
  • 使用 Swift Package Manager 時：請參考 指南，在推播擴充目標中新增 Hive_Extensions
• 手動新增
  • 在 Xcode GUI 中手動新增，或撰寫建置管線腳本進行連結
  • Unreal Engine 不支援獨立的相依性管理工具，因此請以此方式進行
  • 在擴充目標設定的 General > Frameworks and Libraries 中新增 HIVEExtensions.framework

一旦您在开发环境中应用了设置的推送操作按钮，请在从控制台发送推送时指定操作。
在指定操作时，请使用上述详细列表中的类别和操作标识符。

有關控制台設置的更多詳細信息，請參閱控制台指南。

高級實作 (iOS)¶

在 hive_push_actions.json 文件中定義 actions 和 categories 的值。定義後，將 hive_push_actions.json 文件包含在您的目標中並構建應用程式。當應用程式運行時，Hive SDK 會自動解析該文件並在通知中心註冊這些動作和類別。

以下顯示了hive_push_actions.json文件的範例。

{
    "actions": {
        "ACCEPT_ALL_ID": { ... },
        "ACCEPT_ID": { ... },
        "ACCEPT_NOW_ID": { ... },
        "CANCEL_ID": { ... },
        "CLOSE_ID": { ... },
        "CONFIRM_ID": { ... },
        "DECLINE_ID": { ... },
        "EXECUTE_ID": { ... },
        "HOLDING_ID": { ... },
        "PURCHASE_ID": { ... },
        "REJECT_ID": { ... },
        "SALE_ID": { ... }
    },
    "categories": {
        "INFO_CATEGORY": ["CONFIRM_ID"],
        "CLOSE_CATEGORY": ["CLOSE_ID"],
        "CONFIRM_CATEGORY": ["CONFIRM_ID", "CLOSE_ID"],
        "EXECUTE_CATEGORY": ["EXECUTE_ID", "CANCEL_ID"],
        "ACCEPT_ALL_CATEGORY": ["ACCEPT_ALL_ID", "CLOSE_ID"],
        "ACCEPT_NOW_CATEGORY": ["ACCEPT_NOW_ID", "CLOSE_ID"],
        "PURCHASE_CATEGORY": ["PURCHASE_ID", "DECLINE_ID"],
        "SALE_CATEGORY": ["SALE_ID", "DECLINE_ID"]
    }
}

撰寫檔案的注意事項：

• 每個類別（集）的最大按鈕數量為 3。
• 上面的示例定義了默認按鈕集。對於自定義操作按鈕，請勿使用重複的標識符；使用唯一且可區分的字符串。
• 多語言支持遵循 遊戲語言，您可以輸入最多 16 種由 Hive SDK 支持的語言。英語（"en"）是多語言字符串的必需默認值。

常見問題¶

如果自定義操作按鈕在包含文件後仍然不顯示¶

• 檢查文件名是否為'hive_push_actions.json'。
• 確保它已包含在複製捆綁資源中。