# IVS 播放器 SDK：iOS 指南
<a name="player-ios"></a>

Amazon Interactive Video Service (IVS) iOS 播放器提供在 iOS 上使用 Amazon IVS 播放器所需的界面。

**最新版 iOS 播放器：**1.50.0 ([版本備註](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/release-notes.html#mar19-26-player-mobile-ll))

**參考文件：**如需有關 Amazon IVS iOS 播放器中最重要方法的資訊，請參閱參考文件，網址為 [https://aws.github.io/amazon-ivs-player-docs/1.50.0/ios/](https://aws.github.io/amazon-ivs-player-docs/1.50.0/ios/)。

**範本程式碼：**請參閱 GitHub 上的 iOS 範本儲存庫：[https://github.com/aws-samples/amazon-ivs-player-ios-sample](https://github.com/aws-samples/amazon-ivs-player-ios-sample)。

**平台要求：**iOS 14\$1

Amazon IVS 播放器 SDK的 **React Native 包裝函式**可用。如需程式碼和文件，請參閱 [https://github.com/aws/amazon-ivs-react-native-player](https://github.com/aws/amazon-ivs-react-native-player)。

# IVS iOS 播放器 SDK 入門
<a name="ios-getting-started"></a>

本文件將帶您了解開始使用 Amazon IVS iOS 播放器 SDK 的相關步驟。

建議您透過 Swift Package Manager 來整合 SDK。(或者，您可以手動將架構新增到您的專案中。)

## 建議：整合播放器 SDK (Swift Package Manager)
<a name="ios-integrate-sdk-swift"></a>

1. 從 [https://player.live-video.net/1.50.0/Package.swift](https://player.live-video.net/1.50.0/Package.swift) 下載 Package.swift 檔案。

1. 在您的專案中，建立一個名為 AmazonIVSPlayer 的新目錄，然後將其新增至版本控制。

1. 將下載的 Package.swift 檔案放在新目錄中。

1. 在 Xcode 中，前往**檔案 > 新增套件相依性**，然後選取**新增本機...**

1. 導覽至建立的 AmazonIVSPlayer 目錄，將其選取，然後選取**新增套件**。

1. 系統提示您**選擇用於 AmazonIVSPlayer 的套件產品**時，請在**新增至目標**區段中設定應用程式目標，從而選取 **AmazonIVSPlayer** 作為**套件產品**。

1. 選取**新增套件**。

## 替代方法：手動安裝架構
<a name="ios-install-framework-manually"></a>

1. 從 [https://player.live-video.net/1.50.0/AmazonIVSPlayer.xcframework.zip](https://player.live-video.net/1.50.0/AmazonIVSPlayer.xcframework.zip) 中下載最新版本。

1. 解壓縮封存檔的內容。`AmazonIVSPlayer.xcframework` 包含用於裝置和模擬器的 SDK。

1. 內嵌 `AmazonIVSPlayer.xcframework`，方法是將其拖曳至您的應用程式目標的**一般**索引標籤的**架構、程式庫和內嵌內容**部分中：  
![\[您的應用程式目標的一般索引標籤的架構、程式庫和內嵌內容部分：\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/LowLatencyUserGuide/images/iOS_Player_SDK_Guide_xcframework.png)

## 建立播放器
<a name="ios-create-player"></a>

播放器物件為 `IVSPlayer`。它可以被初始化，如下圖所示：

------
#### [ Swift ]

```
import AmazonIVSPlayer

let player = IVSPlayer()
```

------
#### [ Objective-C ]

```
#import <AmazonIVSPlayer/AmazonIVSPlayer.h>

IVSPlayer *player = [[IVSPlayer alloc] init];
```

------

## 設定委派
<a name="ios-setup-delegate"></a>

委派回呼提供有關播放狀態、事件和錯誤的資訊。會在主佇列上調用所有回呼。

------
#### [ Swift ]

```
// Self must conform to IVSPlayer.Delegate
player.delegate = self
```

------
#### [ Objective-C ]

```
// Self must conform to IVSPlayer.Delegate
player.delegate = self
```

------

## 顯示影片
<a name="ios-display-video"></a>

播放器會在自訂圖層中顯示影片，`IVSPlayerLayer`。SDK還提供 `IVSPlayerView`，此圖層支援的 `UIView` 子類別。使用對於您的應用程式 UI 來說更方便的那一個。

在這兩種情況下，透過使用 `player` 屬性從播放器執行個體中顯示影片。

------
#### [ Swift ]

```
// When using IVSPlayerView:
playerView.player = player

// When using IVSPlayerLayer:
playerLayer.player = player
```

------
#### [ Objective-C ]

```
// When using IVSPlayerView:
playerView.player = player;

// When using IVSPlayerLayer:
playerLayer.player = player;
```

------

## 載入串流
<a name="ios-load-stream"></a>

播放器會以非同步方式載入串流。它的狀態表示它何時準備好播放。

------
#### [ Swift ]

```
player.load(url)
```

------
#### [ Objective-C ]

```
[player load:url];
```

------

## 播放串流
<a name="ios-play-stream"></a>

當播放器準備就緒時，請使用 `play` 以開始播放。在 `state` 屬性上使用委託界面或金鑰值觀察，觀察狀態變化。以下為基於委託的方法範例：

------
#### [ Swift ]

```
func player(_ player: IVSPlayer, didChangeState state: IVSPlayer.State) {
    if state == .ready {
        player.play()
    }
}
```

------
#### [ Objective-C ]

```
- (void)player:(IVSPlayer *)player didChangeState:(IVSPlayerState)state {
    if (state == IVSPlayerStateReady) {
        [player play];
    }
}
```

------

## 暫停應用程式背景
<a name="ios-pause-on-app-backgrounding"></a>

當應用程式在背景中時，播放器不支援播放，但不需要完全中斷。暫停就足夠；請參閱下列範例。

------
#### [ Swift ]

```
override func viewDidLoad() {
    super.viewDidLoad()

    NotificationCenter.default.addObserver(self,
        selector: #selector(applicationDidEnterBackground(_:)),
        name: UIApplication.didEnterBackgroundNotification,
        object: nil)
}

@objc func applicationDidEnterBackground(_ notification: NSNotification) {
    playerView?.player?.pause()
}
```

------
#### [ Objective-C ]

```
- (void)viewDidLoad {
    [super viewDidLoad];

    NSNotificationCenter *defaultCenter = NSNotificationCenter.defaultCenter;
    [defaultCenter addObserver:self
                      selector:@selector(applicationDidEnterBackground:)
                          name:UIApplicationDidEnterBackgroundNotification
                        object:nil];
}

- (void)applicationDidEnterBackground:(NSNotification *)notification {
    [playerView.player pause];
}
```

------

## 執行緒安全
<a name="ios-thread-safety"></a>

播放器 API 不是安全執行緒。您應該從應用程式主執行緒中建立並使用播放器執行個體。

## SDK 大小
<a name="ios-sdk-size"></a>

Amazon IVS 播放器 SDK的設計盡可能輕量化。如需開發套件大小的最新資訊，請參閱[版本備註](release-notes.md)。

**重要：**在評估大小影響時，Xcode 產生的 IPA 大小不代表下載到使用者裝置的應用程式大小。App Store 會執行最佳化，以減少應用程式的大小。

## 整合練習
<a name="ios-putting-together"></a>

下面的簡單的檢視控制器程式碼片段會在播放器檢視中加載並播放 URL。請注意，從 XIB/Storyboard 中初始化 `playerView` 屬性，並且[使用「身分檢查器」的「自定義類別」部分](https://developer.apple.com/tutorials/SwiftUI)，在 Interface Builder 中將其類別設為 `IVSPlayerView`。

------
#### [ Swift ]

```
import AmazonIVSPlayer

class MyViewController: UIViewController {
...
    // Connected in Interface Builder
    @IBOutlet var playerView: IVSPlayerView!

    override func viewDidLoad() {
        super.viewDidLoad()

        NotificationCenter.default.addObserver(self,
            selector: #selector(applicationDidEnterBackground(_:)),
            name: UIApplication.didEnterBackgroundNotification,
            object: nil)
    }

    @objc func applicationDidEnterBackground(_ notification: NSNotification) {
        playerView?.player?.pause()
    }
...
    // Assumes this view controller is already loaded.
    // For example, this could be called by a button tap.
    func playVideo(url videoURL: URL) {
        let player = IVSPlayer()
        player.delegate = self
        playerView.player = player
        player.load(videoURL)
    }
}

extension MyViewController: IVSPlayer.Delegate {
    func player(_ player: IVSPlayer, didChangeState state: IVSPlayer.State) {
        if state == .ready {
            player.play()
        }
    }
}
```

------
#### [ Objective-C ]

```
// MyViewController.h

@class IVSPlayerView;

@interface MyViewController: UIViewController
...
// Connected in Interface Builder
@property (nonatomic) IBOutlet IVSPlayerView *playerView;
...
@end


// MyViewController.m

#import <AmazonIVSPlayer/AmazonIVSPlayer.h>

@implementation MyViewController <IVSPlayerDelegate>
...

- (void)viewDidLoad {
    [super viewDidLoad];

    NSNotificationCenter *defaultCenter = NSNotificationCenter.defaultCenter;
    [defaultCenter addObserver:self
                      selector:@selector(applicationDidEnterBackground:)
                          name:UIApplicationDidEnterBackgroundNotification
                        object:nil];
}

- (void)applicationDidEnterBackground:(NSNotification *)notification {
    [playerView.player pause];
}

// Assumes this view controller is already loaded.
// For example, this could be called by a button tap.
- (void)playVideoWithURL:(NSURL *)videoURL {
    IVSPlayer *player = [[IVSPlayer alloc] init];
    player.delegate = self;
    playerView.player = player;
    [player load:videoURL];
}

- (void)player:(IVSPlayer *)player didChangeState:(IVSPlayerState)state {
    if (state == IVSPlayerStateReady) {
        [player play];
    }
}

...
@end
```

------

# IVS iOS 播放器 SDK 中的已知問題和解決方法
<a name="ios-issues"></a>

本文件列出您在使用 Amazon IVS iOS 播放器 SDK 時可能遇到的已知問題，並建議可行的解決方法。
+ 在針對 arm64e 架構進行測試時，播放器可能會遭遇當機問題。這僅適用於特別針對 arm64e 的時候，且不適用於 App Store 建置。

  **解決方法：**不要使用 arm64e。