Questa guida spiega come mantenere il controllo sui tuoi flussi di Streaming Radio MP3/AAC o HLS attivando la protezione tramite chiave unica (token) per decidere, ad esempio, se un ascoltatore può ascoltare la tua radio o meno.

Premessa

• Il principio è semplice: ad ogni connessione, effettuerai una richiesta verso l'API Infomaniak che ti restituirà un token unico con una durata di vita limitata e parametrabile. Questo token autorizzerà chiunque lo possieda a consumare il flusso durante questo periodo.
• È possibile proteggere un flusso MP3/AAC o HLS indipendentemente l'uno dall'altro (stessa cosa per la geolocalizzazione).
• L'attivazione della restrizione comporta una modifica della configurazione del flusso che può richiedere alcuni minuti per essere replicata sui server.

Proteggere un flusso audio con una chiave univoca

Per farlo, basta andare nelle impostazioni delle restrizioni e attivare la protezione tramite token sul flusso che si desidera proteggere:

1. Clicca qui per accedere alla gestione del tuo prodotto su Manager Infomaniak (hai bisogno di aiuto?).
2. Clicca direttamente sul nome attribuito al prodotto interessato.
3. Fai clic sul nome del flusso audio interessato.
4. Clicca su Restrizioni nel menu laterale sinistro.
5. Scegliete HLS se necessario.
6. Clicca sul menu d'azione ⋮ situato a destra dell'elemento interessato.
7. Clicca su Restrizione per token:
   
    

Attiva quindi la protezione.

Attenzione, nel momento in cui attiverete questa opzione, l'accesso al flusso sarà istantaneamente bloccato per le nuove connessioni. Adattate i vostri player per tenere conto della restrizione, come illustrato nell'esempio qui sotto:

Creare un token API Radio

Per accedere all'API Radio, devi prima autenticarti utilizzando un token applicazione. Questa operazione va eseguita una sola volta. Per creare questo token applicazione, consulta questa guida.

L'ambito è radio e la durata di vita illimitata per evitare di dover rigenerare un codice in modo regolare. Una volta generato il token, copiarlo e incollarlo nell'esempio qui sotto.

Esempio di utilizzo in linguaggio PHP

Per MP3/AAC o HLS, il codice può essere sostanzialmente lo stesso, cambia solo l'URL chiamata in POST nella sua forma.

if (!defined('API_TOKEN')) {
     define('API_TOKEN', 'AYF5lSh3c7Xy5974Fs12RTkTThujT-L9R4Xk2ZfGyP6sV7QqJ1oC3jD8nFtKzIxUeMw5oNzR6');
}
/**
 * Fonction générique pour executer des requêtes cURL
 *
 * @param string $method Méthode HTTP (GET, POST, PUT, etc...)
 * @param string $url Url de l'api a requêter
 * @param array $headers Liste des en-têtes HTTP (l'autorisation doit être passée ici avec un ['Authorization: Bearer ']
 * @param array $payload Un tableau contenant les données pour créer un token
 * @return mixed
 */

function request(string $method, string $url, array $headers = [], array $payload = []): mixed{
    // prepare options array
    $opts = [
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_URL => $url,
        CURLOPT_CUSTOMREQUEST => strtoupper($method),
    ];

    // add payload if relevant
    if ($payload && $method !== 'GET') {
        $opts[CURLOPT_POSTFIELDS] = json_encode($payload);
    }
    $ch = curl_init();
    curl_setopt_array($ch, $opts);
    $result = curl_exec($ch);
    if(curl_errno($ch)){
        throw new Exception(curl_error($ch));
    }
    $data = json_decode($result, true);
    if ($data['result'] === 'error') {
        throw new Exception($data['error']['description'] ?? 'an error occured');

    }
    return $data['data'];
}

Creeremo il token, l'URL di creazione del token si compone come segue:

• Per un flusso MP3/AAC

POST https://api.infomaniak.com/1/radios/acl/streams/mountpoint.mp3/token

Esempio per proteggere https://newradiotest.ice.infomaniak.ch/newradiotest-128.aac la rotta sarà: https://api.infomaniak.com/1/radios/acl/streams/newradiotest-128.aac/token

• Per un flusso HLS

POST https://api.infomaniak.com/1/radios/acl/hls_streams/<stream>/token

Esempio per proteggere https://myradiostream.radiohls.infomaniak.com/myradiostream/manifest.m3u8 la rotta sarà: https://api.infomaniak.com/1/radios/acl/hls_streams/myradiostream/token

Esempio nel caso di MP3/AAC, assicurati di regolare:

$token = request(
    'POST',
   'https://api.infomaniak.com/1/radios/acl/streams/newradiotest-128.aac/token',
    // en-tête d'authorization
    [
        'Authorization: Bearer ' . API_TOKEN,
        'Content-Type: application/json',
    ],
    /**
     * payload pour créer le token, vous pouvez passer les valeurs suivantes
     * window     | 300               | optionnel | durée de validité du token (default: 5 minutes)
     */

    [
        'window' => 3600, // 1h validity
    ]
);

È importante notare che se questo codice viene generato al momento del caricamento della pagina, l'ascoltatore avrà "window" secondi per avviare la riproduzione del flusso. Oltre questo intervallo di tempo, il token scadrà e il flusso non potrà più essere avviato a meno che la pagina non venga ricaricata. A seconda delle vostre esigenze e del vostro caso d'uso, sarà necessario regolare questo intervallo nel miglior modo possibile.

Dovrete anche sostituire di seguito l'URL di riproduzione del vostro flusso al posto di quello indicato, mantenendo il parametro $token alla fine. Infine, visualizziamo il Player (qui una semplice etichetta html5, ma è possibile aggiungere qualsiasi sovrapposizione dopo, il token essendo passato nei parametri $_GET dell'url).

$streamUrl = "https://newradiotest.ice.infomaniak.ch/newradiotest-128.aac?$token";
echo "<audio controls=""><source src="$streamUrl"></audio>";

Questa guida dettaglia la configurazione di un Player per la tua Streaming Radio Infomaniak.

Prerequisiti

• Aggiungere 1 Player utilizzando il modello Infomaniak.

Configurare le opzioni del Player Infomaniak

Una volta che hai collegato il tuo flusso al tuo Player e che il tuo Player è creato:

1. Clicca qui per accedere alla gestione del tuo prodotto su il Manager Infomaniak (hai bisogno di aiuto?).
2. Clicca direttamente sul nome assegnato al prodotto interessato.
3. Clicca su I miei player nel menu laterale sinistro.
4. Fai clic sul nome del Player da configurare (o crea un nuovo lettore):
   

1. Scheda Aspetto

Qui è dove puoi scegliere la dimensione del lettore (grande, media, mini o lettore multi radio) e la sua percentuale di visualizzazione.

È possibile personalizzare i colori dello sfondo, dei pulsanti e del testo:

Un interruttore a scorrimento (toggle switch) consente di attivare o disattivare la visualizzazione dei brani trasmessi, con o senza i loro orari di trasmissione:

• Prendete visione dei dettagli a riguardo alla fine di questa guida.

Il Player può visualizzare:

• un'illustrazione che rappresenta la copertina dell'album, o un'immagine di riserva se non è disponibile,
• un'immagine fissa (3 Mo max.),
• il logo della tua radio, da personalizzare qui:
  
• una visualizzazione dello spettro audio (Spettrogramma / Spettro).

2. Scheda Diffusione

Qui è dove è possibile collegare i vostri flussi radio (HLS o meno) al vostro Player in fase di configurazione.

Consulta questa altra guida riguardo alle opzioni proposte per la gestione del live:

3. Scheda Miniature

Qui è dove è possibile caricare le immagini visibili quando il flusso è in caricamento o non disponibile/limitato.

4. Scheda Informazioni del lettore

Qui è che puoi nominare il tuo Player e decidere di mostrare o nascondere:

• il titolo e l'artista al posto del nome della radio,
• il numero di ascoltatori,
• il logo Infomaniak.

5. Scheda Opzioni di condivisione

Un interruttore a scorrimento (toggle switch) consente di attivare o disattivare alcuni servizi come Facebook. Una volta attivato, un pulsante di condivisione per questi servizi sarà visibile sul tuo Player:

Dettagli della cronologia di trasmissione (scheda #1)

La cronologia di trasmissione consente di riascoltare le musiche trasmesse (tra 1 e 40) se il tuo flusso è di tipo HLS (potrai quindi definire un buffer da 25 secondi a 2 ore):

La funzione di ritorno indietro e di riascolto non è attivata per impostazione predefinita: rimane opzionale per rispettare le restrizioni di alcuni paesi o stazioni radio. Una volta attivata, il gestore della radio può scegliere quali flussi saranno disponibili per la trasmissione (vedi scheda #2 sopra), mentre l'ascoltatore può selezionare la qualità di ascolto nel Player:

Posizione & integrazione della cronologia di trasmissione

L'elenco è consultabile a scelta:

• direttamente sotto il Player,
• sul Player,
• o trasferibile nell'integrazione del tuo sito web…

In effetti, è possibile visualizzare la cronologia in una seconda iframe, separata da quella del Player principale. Esempio di URL per il Player:
https://player-radio.infomaniak.com/2/prod/super/7cbaa24a-3510-47a4-b41e-b99218bfd507

E per la cronologia esterna:
https://player-radio.infomaniak.com/2/prod/history

I due iframe devono essere integrati nella stessa pagina e comunicano tra loro per aggiornare la cronologia o avviare un brano precedentemente trasmesso.

Un secondo modo di integrazione permette di visualizzare una cronologia autonoma, senza iframe principale. Basta aggiungere l'ID del Player all'URL:
https://player-radio.infomaniak.com/2/prod/history/7cbaa24a-3510-47a4-b41e-b99218bfd507

Questo modo è adatto, ad esempio, agli utenti di un altro Player che desiderano visualizzare solo la cronologia dei brani.

Questa guida spiega come trasferire i flussi audio presenti su una delle tue Radio Streaming Infomaniak verso un'altra delle tue radio, presente nella stessa Organizzazione.

Trasferire i flussi audio

Per fare questo:

1. Clicca qui per accedere alla gestione del tuo prodotto su Manager Infomaniak (hai bisogno di aiuto?).
2. Clicca direttamente sul nome attribuito al prodotto interessato.
3. Clicca sul menu delle azioni ⋮ situato a destra dell'elemento interessato.
4. Scegliere Trasferire:
   
5. Cerca e conferma il nome dell'altra radio che possiedi nella stessa Organizzazione.
6. Conferma il trasferimento:
   

Aggiorna le pagine del Manager se necessario per aggiornare le informazioni visualizzate.