Integration Guide

This document provides a comprehensive guide for developers looking to integrate the aPlayer application into their own systems, whether they are mobile applications (iOS/Android) or websites. aPlayer offers seamless video playback, offline content management, and shortcut functionalities via app links.

Overview of App Links

aPlayer leverages deep linking (App Links) to enable external applications or websites to trigger specific functionalities within the aPlayer app. This allows for a smooth and integrated user experience.

All app links follow a base URL structure:

              https://aplayer.co/appLink/

Add & Open Shortcut

This functionality allows you to add a new shortcut (addShortcut) to the aPlayer home screen or open an existing one (openShortcut).


              https://aplayer.co/appLink/addShortcut?title={TITLE}&url={URL}&mode={MODE}
              https://aplayer.co/appLink/openShortcut?title={TITLE}&url={URL}&mode={MODE}

Parameters:

(All parameters must be URL-encoded)

TITLE (required) : The title of the shortcut. URL-encoded.

URL (required) : The URL that the shortcut will open when tapped. This can be any valid web URL or another app link. URL-encoded.

MODE (optional) :

  • If mode=app, the shortcut will be treated as a "web app," potentially opening in a dedicated web view within the aPlayer app.
  • If mode is omitted or has any other value, it will be a standard website shortcut.

Example:

https://aplayer.co/appLink/addShortcut?title=Google&url=https://google.com&mode=app

Try it!

Play Video & Offline Video

This functionality allows you to initiate video playback (playVideo) or trigger the download of video content for offline viewing (offlineVideo) directly within the aPlayer app. Both functions share the same app link format and parameters.


              https://aplayer.co/appLink/playVideo?title={TITLE}&description={DESCRIPTION}&poster={POSTER}&source={SOURCE}&key={KEY}
              https://aplayer.co/appLink/offlineVideo?title={TITLE}&description={DESCRIPTION}&poster={POSTER}&source={SOURCE}&key={KEY}

Parameters:

(All parameters must be URL-encoded)

TITLE (required) : The title of the video to be displayed in the player.

DESCRIPTION (optional) : A brief description of the video.

POSTER (optional) : URL to an image that will be displayed as the video's poster (thumbnail) before playback begins.

SOURCE (required) : Encrypted JSON string containing the video's actual source URL, format, subtitles, and optional headers.

KEY (required) : Encrypted AES secret key used to encrypt the source parameter.

Example:

https://aplayer.co/appLink/addShortcut?title=Google&url=https://google.com&mode=app

Try it!

Encryption for SOURCE and KEY:

For security reasons, the source and key parameters are encrypted using a combination of AES and RSA algorithms.


1. Source Encryption (AES):

The source data (which is a JSON string) is encrypted using AES (Advanced Encryption Standard) with the AES/ECB/PKCS5Padding mode and a 128-bit secret key that you (the integrator) define. This ensures that the video's actual URL and related sensitive information are protected.


JSON Format for source data:


                
    
                  
  • url (string, required): The
                    direct
                    URL to the video file.
    • 
                  
  • format (string, required): The
                    format of the video (e.g., "mp4", "m3u8", "dash").
    • 
                  
  • subtitles (array of objects, optional): An array
                    of
                    subtitle tracks.
    • 
                  
      
                    
    • url (string, required): The
                      direct URL to the subtitle file.
      • 
                    
    • name (string, required): The
                      display name of the subtitle track (e.g., "English", "Vietnamese").
      • 
                    
    • language (string, required):
                      The
                      language code for the subtitle (e.g., "en", "vi").
      • 
                    
    • format (string, required): The
                      format of the subtitle file (e.g., "srt", "vtt").
      • 
                    
    • is_default (boolean, optional): Indicates
                      whether
                      this subtitle should be selected by default.
      • 
                  
    
                  
  • headers (object, optional): Custom HTTP headers
                    to
                    be included in the video request.
    • 
                

                

                
2. Key Encryption (RSA):

                
The AES secret key (which you used to encrypt the source data) is then encrypted
                  using RSA (Rivest–Shamir–Adleman) with the RSA/ECB/PKCS1Padding mode and a 2048-bit key
                  pair using our
                  public key. This allows the APlayer app to securely decrypt your AES secret key and subsequently
                  decrypt
                  the source data.

                

                
Our Public RSA Key:

                

                

                
3. Encryption Steps:

                
    
                  
  • Prepare source JSON: Create the JSON string for your video data.
    • 
                  
  • Generate AES Secret Key: Generate a strong, random AES secret key.
    • 
                  
  • Encrypt source: Encrypt the source JSON string using the generated AES secret
                    key.
                  
    • 
                  
  • Encrypt AES Secret Key: Encrypt the generated AES secret key using our provided
                    RSA
                    public key.
    • 
                  
  • URL-encode: URL-encode both the encrypted source and encrypted key before
                    constructing the app link.
    • 
                

                

                
4. Code Samples for Encryption

                
This section provides code examples in Javascript to help you implement the AES data
                  encryption and RSA key encryption as
                  required for the playVideo and offlineVideo app links.

                

                
AES Encryption (for source data):

                
<!-- Include CryptoJS library (for AES) -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.2.0/crypto-js.min.js"></script>

<script>
  function encryptSourceData(data, key) {
    const keyBytes = CryptoJS.enc.Utf8.parse(key);
    const encrypted = CryptoJS.AES.encrypt(data, keyBytes, {
      mode: CryptoJS.mode.ECB,
      padding: CryptoJS.pad.Pkcs7
    });
    return encrypted.toString();
  }
</script>

                

                
RSA Encryption (for AES key):

                
<!-- Include JsEncrypt library (for RSA) -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/jsencrypt/3.3.2/jsencrypt.min.js"></script>

<script>
  function encryptAesKey(key) {
    const encryptor = new JSEncrypt();
    encryptor.setPublicKey(RSA_PUBLIC_KEY);
    return encryptor.encrypt(key);
  }
</script>