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

Premessa

• Ad ogni connessione, effettuerete una richiesta all'API Infomaniak che vi restituirà un token unico con una durata limitata e parametrabile.
• Questo token autorizzerà chiunque lo possieda a consumare il flusso durante questo periodo.
• Potete proteggere un flusso MP3/AAC o HLS indipendentemente l'uno dall'altro (stesso discorso per la geolocalizzazione, del resto).
• 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 chiave unica

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

1. Cliccate qui per accedere alla gestione del vostro prodotto sul Manager Infomaniak (bisogno di aiuto?).
2. Cliccate direttamente sul nome attribuito al prodotto interessato:
   
3. Cliccate:
   1. oppure sul nome della radio:
      
   2. oppure su Restrizioni nel menu laterale sinistro per applicare restrizioni all'intero prodotto:
      
4. Quando scegliete a sopra, cliccate poi su Restrizioni nel menu laterale sinistro.
5. Scegliete HLS se necessario.
6. Cliccate sul menu di azione ⋮ situato a destra dell'elemento interessato.
7. Cliccate su Restrizione con token:
   
    

Attivate quindi la protezione.

Attenzione, nel momento in cui attivate questa opzione, l'accesso al flusso sarà immediatamente 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, è necessario autenticarsi innanzitutto con un token di applicazione. Questa operazione va eseguita una sola volta. Per creare questo token di applicazione, consultare questa altra guida.

Lo scope è radio e la durata è illimitata per evitare di dover rigenerare un codice in modo regolare. Una volta generato il token, copiarlo per 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 a livello della 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'];
}

Vediamo come creare il token, l'URL di creazione del token si scompone 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 il percorso 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 il percorso sarà: https://api.infomaniak.com/1/radios/acl/hls_streams/myradiostream/token

Esempio nel caso del MP3 / AAC, ricordarsi 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 esigenze e del caso d'uso, sarà necessario regolare questo intervallo nel modo migliore possibile.

Sarà anche necessario sostituire qui sotto l'URL di lettura del proprio flusso al posto di quella indicata mantenendo il parametro $token alla fine. E per finire, si visualizza il Player (qui una semplice etichetta html5, ma si può aggiungere ovviamente 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>";