Guida introduttiva all'SDK IVS Player per iOS

Questo documento illustra i passaggi necessari per iniziare a utilizzare l'SDK Amazon IVS Player su iOS.

Si consiglia di integrare l'SDK del lettore tramite Swift Package Manager. (In alternativa, esiste la possibilità di eseguire l’integrazione tramite CocoaPods o aggiungendo manualmente il framework al proprio progetto).

Consigliato: Integrare l'SDK del lettore (Swift Package Manager)

1. Scaricare il file Package.swift da https://player.live-video.net/1.43.0/Package.swift.

2. Nel tuo progetto, creare una nuova directory denominata AmazonIVSPlayer e aggiungila al controllo delle versioni.

3. Inserire il file Package.swift file nella nuova directory.

4. In Xcode, vai su File > Aggiungi dipendenze del pacchetto e seleziona Aggiungi locale…

5. Passare alla directory AmazonIVSPlayer creata e selezionare Aggiungi pacchetto.

6. Quando viene richiesto di scegliere i prodotti del pacchetto per AmazonIVSPlayer, selezionare AmazonIVSPlayer come prodotto del pacchetto impostando la destinazione dell'applicazione nella sezione Aggiungi alla destinazione.

7. Seleziona Aggiungi pacchetto.

Approccio alternativo: integrare l'SDK del lettore (CocoaPods)

Importante: CocoaPods è in modalità di manutenzione (solo correzioni di sicurezza) e dopo dicembre 2026 non è possibile pubblicare nuovi pacchetti o aggiornamenti nel repository CocoaPods. I pacchetti esistenti rimarranno disponibili ma congelati. Consigliamo di utilizzare Swift Package Manager per tutti i nuovi progetti.

I rilasci sono pubblicati tramite CocoaPods sotto il nome AmazonIVSPlayer. Aggiungere questa dipendenza al proprio Podfile:

pod 'AmazonIVSPlayer'

Eseguire pod install e l'SDK sarà disponibile nel .xcworkspace.

Approccio alternativo: installare manualmente il framework

1. Scaricare l'ultima versione da https://player.live-video.net/1.43.0/AmazonIVSPlayer.xcframework.zip.

2. Estrai i contenuti dell'archivio. AmazonIVSPlayer.xcframework contiene l'SDK sia per il dispositivo sia per il simulatore.

3. Incorporare AmazonIVSPlayer.xcframework trascinandolo nella sezione Framework, librerie e contenuto incorporato della scheda Generali per il target dell'applicazione:

   

Creare lettore

L'oggetto lettore è IVSPlayer. Può essere inizializzato come illustrato di seguito:

Swift

import AmazonIVSPlayer

let player = IVSPlayer()

Objective-C

#import <AmazonIVSPlayer/AmazonIVSPlayer.h>

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

Configurazione di delegati

I callback delegati forniscono informazioni sullo stato di riproduzione, eventi ed errori. Tutti i callback vengono richiamati nella coda principale.

Swift

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

Objective-C

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

Visualizzare video

Il lettore visualizza il video in un livello personalizzato, IVSPlayerLayer. L'SDK fornisce inoltre IVSPlayerView, una sottoclasse UIView supportata da questo livello. È possibile usare il più conveniente per l'interfaccia utente dell'applicazione.

In entrambi i casi, visualizzare il video da un'istanza del lettore utilizzando la proprietà 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;

Caricare un flusso

Il lettore carica il flusso in modo asincrono. Il suo stato indica quando è pronto per la riproduzione.

Swift

player.load(url)

Objective-C

[player load:url];

Riprodurre un flusso

Quando il lettore è pronto, usare play per iniziare la riproduzione. Utilizzare l'interfaccia delegato o l'osservazione di chiavi-valori sulla proprietà state per osservare il cambiamento di stato. Di seguito viene riportato un esempio dell'approccio basato su delegati:

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];
    }
}

Mettere in pausa quando l'app è in background

Il lettore non supporta la riproduzione mentre l'app è in background, ma non è necessario che venga chiuso del tutto. È sufficiente mettere in pausa; vedere gli esempi di seguito.

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];
}

Sicurezza del thread

L'API del lettore non è thread-safe. È necessario creare e utilizzare un'istanza del lettore dal thread principale dell'applicazione.

Dimensione dell'SDK

Gli SDK Amazon IVS Player sono progettati per essere il più leggeri possibile. Per informazioni aggiornate sulle dimensioni dell'SDK, consultare Note di rilascio.

Importante: quando si valuta l'impatto delle dimensioni, la dimensione dell'IPA prodotta da Xcode non è rappresentativa della dimensione dell'app scaricata sul dispositivo di un utente. L'App Store esegue ottimizzazioni per ridurre le dimensioni dell'app.

Mettere tutto insieme

Il seguente frammento semplice di controller di visualizzazione carica e riproduce un URL in una visualizzazione del lettore. Tenere presente che la proprietà playerView viene inizializzata da un XIB/Storyboard e che la sua classe è impostata su IVSPlayerView nell'Interface Builder utilizzando la sezione Classe personalizzata dell'Inspector dell'identità.

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