Everlink provides Javascript functionality in the form of the Everlink library. Add Everlink to your project directly from our CDN using a script tag:

 // requires account approval

This will expose the Everlink library. Initiate the class with your Everlink appID, which you can find in the account page. You will not be able to use the library without a valid appID:


 const everlink = new Everlink(appID);

An error will be thrown if you attempt to make a call to the server with an invalid appID. It is possible to add a function to run when an error occurs if desired using:


 everlink.onError = () => {
 // do stuff when an error occurs
 };

onError takes an object with an error code and message E.g. error = { code: ’EJ1’, message: ’Everlink Error: Invalid Everlink appID’ }. If onError is not set the error will be thrown normally and need catching. Otherwise the callback function will run.

Usage

There are two parts to the functionality of the Everlink library, emitting audio codes and listening for them, generally performed by the business and the patron, respectively.

Generating a token

It is possible to generate a token within the SDK. This token can either be directly accessed from the returned value or using the onNewTokenGenerated callback.

You can access new tokens when generated using the method onNewTokenGenerated. This will allow you to use the token for your own database:


 everlink.onNewTokenGenerated = (token) => {
 // do stuff when a new token is generated
 };

getNewToken()

getNewToken() is an asynchronous function that takes a validity start date in the form ‘YYYY-MM-DD’. The token will be valid for two weeks after this date. If no validity date is provided then it will be the current date.


  await everlink.getNewToken();

startListening({isOffline})

startListening() is an asynchronous function that will gain access to the user's microphone and begin listening for an authorisation sequence. When it detects an audio code it will either perform the matching locally, or send it to our servers and return a token corresponding to the audio code, depending on whether isOffline is true or false.

There are two ways of accessing this token. The onTokenFromAudio method allows you to declare a function that will run when the token is returned, taking in an object with a token and error key. If a correct token is returned the error will be null. If there is an expired token returned then there will be an error and token will be null. E.g. { token: ‘exampleToken123’, error: null }.


 everlink.onTokenFromAudio = (tokenObj) => {
 // do stuff using tokenObj.token and tokenObj.error
 }

 await everlink.startListening({isOffline:true});

Alternatively, startListening will also return the token:


 const token = await everlink.startListening({isOffline:true});
 // do stuff using the token

This function will keep listening for a sound until it receives a token from the server or is stopped with stopListening(). It is also not possible to call startListening() again until either a token is returned, or stopListening() is called.

stopListening()

stopListening() is a synchronous function that will cause Everlink to stop listening and disconnect from the microphone. For example, with startListening() already running, call:


 everlink.stopListening();

Emitting audio codes

startPlaying()

startPlaying() is an asynchronous function that plays using a generated token. This will be generated the first time that the function is called and then stored in the browser. If the token expires or the cache is cleared then a new token will again be generated. The validity start date of the generated token will be the current date. Call the function with:


await everlink.startPlaying({isOffline:true});

You can access new tokens when generated using the method onNewTokenGenerated. This will allow you to use the token for your own database:


 everlink.onNewTokenGenerated = (token) => {
 // do stuff when a new token is generated
 };

playFromToken(token, {isOffline})

playFromToken() is an asynchronous function that takes in a token and an object containing the boolean isOffline. If isOffline is true then the token will be searched for in the stored tokens, otherwise a call will be made to the server.


await everlink.playFromToken(‘exampleToken12345’, {isOffline:true);

Both playFromToken() and startPlaying() will continue playing audio until stopped with stopPlaying(). It is not possible to call an Everlink function to play audio until the existing audio has been stopped.

stopPlaying()

stopPlaying() is a synchronous function that will stop the audio being played and allow another emitting function to be called. Call this with:


 everlink.stopPlaying();

Downloading Tokens
(Only needed if you want the SDK to work offline)

saveSounds() is an asynchronous function that takes in an array of token strings and stores the in the browser.


 everlink.saveSounds(
     [
         'exampleToken12345',
         'exampleToken12346',
         'exampleToken12347'        
     ]
 ));

Call clearSounds() To delete all saved tokens and their corresponding audio codes


 everlink.clearSounds

Below is an example app showing how to use Everlink's functions:


 /*
 * Copyright 2021 Everlink. All rights reserved.
 *
 *
 * You may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://everlink.co/downloads/terms-of-use.pdf
 *
 * Unless required by applicable law or agreed to in writing, software distributed under
 * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 * ANY KIND, either express or implied. See the License for the specific language governing
 * permissions and limitations under the License.
 */
<html>
<head>
     <meta charset="utf-8" />
     <title>Everlink</title>
          <script src="// requires account approval"></script>
    </head>
      
<body>
      <h1>My Sample Token App</h1>
      <button id="recordButton">Record</button>
      <button id="stopButton">Stop</button>
      <button id="playButton">Play</button>
      <button id="playConstant">Play Constant</button>
      <button id="stopPlaying">Stop Playing</button>
</body>

<script>
    const everlink = new Everlink('myAppID12345');

    everlink.onError = (err) => {
        console.log(err.code);
        console.log(err.message);
    };

    everlink.onTokenFromAudio = (tokenObj) => {
        if (tokenObj.token) {
            const { token } = tokenObj;
            console.log('token from audio: ', token);
            alert(token);
        } else if (tokenObj.error){
            const { error } = tokenObj;
            console.log('error from audio: ', error);
        }
    };

    everlink.onNewTokenGenerated = (token) => {
        console.log('new token generated: ', token);
    };

    const playConstantSound = (token) => {
        everlink.playFromToken('exampleToken12345', { isOffline: false });
    };

    const updateToken = async () => {
     await everlink.getNewToken('2021-12-16');
    };

    const stopPlaying = document.getElementById('stopPlaying');
    stopPlaying.addEventListener('click', everlink.stopPlaying);

    const recordButton = document.getElementById('recordButton');
    recordButton.addEventListener('click', () => everlink.startListening({ isOffline:false }));

    const stopButton = document.getElementById('stopButton');
    stopButton.addEventListener('click', everlink.stopListening);

    const playConstant = document.getElementById('playConstant');
    playConstant.addEventListener('click', playConstantSound);

    const playButton = document.getElementById('playButton');
    playButton.addEventListener('click', everlink.startPlaying);
    
    const tokenButton = document.getElementById('newToken');
    tokenButton.addEventListener('click', updateToken);
    
    const saveButton = document.getElementById('saveSounds');
    saveButton.addEventListener('click', () => everlink.saveSounds(
    [
        'exampleToken12345',
        'exampleToken12346'        
    ]
    ));

    const clearButton = document.getElementById('clearSounds');
    clearButton.addEventListener('click', everlink.clearSounds);
    
</script>
</html>