Skip to main content

SDK

  • What are the benefits of Browser SDK source code being publicly available?

    Plivo’s Browser SDK codebase is now publicly available, and it supports TypeScript. We made the code available to offer developers several benefits:

    • Transparency — The code is now available for anyone to see and to contribute to. Every library has owners who control final edits, but anyone in the developer community can make suggestions and take part.
    • QA — Collaborators can work together to perfect the code, so bugs can be discovered and fixed faster.
    • Customizable — You have more freedom to make the tweaks and edits you want.
    • Community We welcome community contributions and pull requests. The global community can introduce new concepts and capabilities faster.
    • Reliability — Having the codebase being reviewed by our internal team and the community gives us robust, tried, and tested code.
    • Agility — If you wish to make changes quickly, you can, depending on your needs. For example, if you wish to add push notifications in any scenario, you can do it yourself.
  • Does Plivo's Browser SDK support TypeScript?

    Yes, we support TypeScript in our Browser SDK. This post explains the advantages of using TypeScript for JavaScript development.

    What is TypeScript?  

    TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. TypeScript envelopes normal JavaScript and adds additional functions. It eliminates whole classes of bugs and improves the development process.

    Why TypeScript?

    JavaScript is fast, simple, and easy to learn. It's a dynamically typed language, meaning that variables’ types are assigned at run time. TypeScript keeps this from becoming a problem through its type checking feature. 

    What are the benefits of TypeScript?

    You can credit Typescript's rapid growth to several prominent benefits:

    1. Static typing helps developers write more robust code by detecting bugs while writing scripts, resulting in better, cleaner code compared to JavaScript. 

    Example: Here’s a code snippet where we’ve defined a string value for a variable, when actually it should have been an integer. You can see how the SDK itself throws a type error to change the value to an integer during compile time. 

    Screenshot_2021-01-21_at_3.11.12_PM.png

    2. Type annotations: One of the main objectives of TypeScript is to identify static constructs that are possible errors. Its ability to do this allows developers to make safe assumptions about state while in execution. 

    In this example, you can see how Type annotations prevent operations from executing if the object type is unexpected. This helps developers avoid these kinds of bugs at compile time. 

    Screenshot_2021-01-21_at_3.11.48_PM.png

    3. Better for collaboration: When teams of developers build large-scale applications you have an increased chance of coding errors. The type safety technique in TypeScript helps developers find code errors while writing the code and not during compilation, which results in a more efficient debugging process and better collaboration opportunity.

    4. Enhanced productivity: TypeScript builds in features like auto compilation, ECMAScript 6 code support, and dynamic typing that help the compiler create highly optimized code and boost developers' productivity.

    You can see the capabilities of our Browser SDK by checking out some sample applications and start using it yourself with help from our Browser SDK documentation.

  • Are there any functional or performance limitations while using the Plivo Browser SDK on mobile browsers?

    We've tested our Browser SDK on mobile browsers and documented functional and performance-related issues in this post to help you implement nuanced workflows and understand what resources may be needed by your apps. 

    The Browser SDK supports most of the functionality available in Chrome, Firefox, and Safari, but some functionality differs between the browsers. This table highlights the functional differences:

    Functional

    Browser Chrome Firefox Safari
    Make and receive calls Supported Supported Supported
    Mute and unmute Supported Supported Supported
    Support for DTMF Supported Supported Supported
    Call-quality metrics tracking Supported Supported Not supported
    Microphone and speaker toggling Supported Not supported Not supported
    Move browser to background during ongoing call Call continues Call continues Call continues
    Receive incoming call when browser is in background Rings only when the browser is brought to the foreground and then the call can be answered as usual Rings only when the browser is brought to the foreground and then the call can be answered as usual
    Rings only when the browser is brought to the foreground and then the call can be answered as usual
    Incoming PSTN call during ongoing SDK call Both calls happen in parallel SDK call is overwritten by PSTN call (audio running in background and no audio heard from app), but when PSTN call is disconnected, SDK call continues
    Both calls happen in parallel
    Echo cancellation and noise reduction Supported Supported Supported

     

    Performance

    In this table we analyze the performance aspects of using the Browser SDK on mobile browsers. If you notice behavior that differs from this information, please reach out to us via our support portal

    Browser Chrome Firefox Safari
    CPU usage on call Max 7%
    The browser doesn’t provide this information at the JavaScript library (SDK) level
    11.6%
    CPU usage idle state Max 1% 1.9%
    Memory consumption on call Max 5MB Max 4.8MB
    Memory consumption idle state Max 3.1MB Max 4.8MB
    Network usage Total requests: 23
    Transferred over network: 645B
    Resources loaded by the page: 1MB
    Finish: 1.55 sec (async loading of objects)
    Total requests: 7
    Transferred over network: 1.26KB
    Resources loaded by the page: 778.32KB
    Finish: 19.88 sec (async loading of objects)
    DOMContentLoaded: 121 ms
    Load: 142 ms
    Domains: 4
    Resources: 6
    Total loaded: 2.97KB
    Bytes transferred: 536
    Time: 0
    Jitter 4 ms No jitter No jitter
    RTT 122 ms 105.91 ms, 100.12 ms
    150.48 ms, 100.28 ms
    Packet loss No packet lost 0.03% (No packet lost) No packet lost

     

  • Can I receive calls using Plivo client SDKs?

    Yes. Our Plivo client SDKs are all capable of receiving incoming calls from any Plivo endpoints.

  • What can I build with the Plivo client SDKs?

    You can easily build any voice-enabled browser or mobile application using one of our Plivo client SDKs. For details, see our Getting Started guides, which include sample applications:

  • What are the costs associated with Plivo client SDKs?

    There's no cost for developers to use one of the Plivo client SDKs. Calls placed or received using a Plivo client SDK are charged the same per-minute rates anywhere in the world. These endpoint types are categorized as “Client SDK and SIP calls” on our pricing page

    Two-way calls — calls that connect two parties — have two types of call-related legs:

    • One connecting the Plivo client SDK to Plivo
    • One connecting other parties to Plivo

    Pricing depends on the calling number, destination, and number type. For a complete pricing breakdown, visit our pricing page.

  • How does a Plivo client SDK interact with Plivo APIs?

    You can use a Plivo client SDK to add voice functionality to client applications on mobile devices and through web browsers. Plivo’s APIs and XML code control calls on the server side. The two sides interact with each other and work in tandem — Plivo’s APIs and XML elements control SDK calls for actions such as playing text to speech and recording a call.

  • Do the Plivo client SDKs work internationally?

    Yes, Plivo client SDKs can be used domestically or internationally for incoming and outgoing calls.

  • How do I get started with Plivo client SDKs?

    Plivo client SDKs makes it easy to use a web browser or mobile device to send and receive voice calls using two-way audio streaming over a data connection.

    For more information, check out our Getting Started guides, which include sample applications:

  • Can I make calls to SIP endpoints using Plivo client SDKs?

    Yes. Applications written with Plivo client SDKs act like any phone that works with Plivo. They use the same Plivo XML and can connect to any SIP endpoint, Plivo or non-Plivo.

  • Can I make calls to traditional phone numbers using the Plivo client SDKs?

    Yes. Applications written using Plivo client SDKs act like any phone that works with Plivo. They can connect to any existing phone number using the same Plivo XML.

  • What are the rules for SIP headers?

    SIP headers (also called SIP fields or extra headers) carry message attributes to ensure that data packets travel along the correct path when communicating between devices on separate networks.

    SIP headers are present for every HTTP request made by an outbound call. They can be categorized into four main types: record route headers, route headers, via headers, and contact headers. SIP headers are similar to HTTP header fields and always use the format

    <header_name>:<value>

    Follow these rules for header names:

    • Write headers in the format: X-PH-Yourfield
    • “Yourfield” must start with an uppercase letter. Other characters must be in lowercase.
    • The header name can only contain alphanumeric characters (A-Z, a-z, 0-9).
    • The header name can have a maximum length of 24 characters.

    Following these rules for header values:

    • The header value can only contain alphanumeric characters (A-Z, a-z, 0-9) and %.
    • The header value can have a maximum length of 48 characters.

    Header name-value pairs that don't follow these rules will not be sent by Plivo. 

  • Can the onLogout event be triggered without explicitly calling the logout API?

    Yes. The onLogout event may be triggered for any of several reasons.

  • What is DSCP used for?

    Browser SDK allows users to enable DSCP using the "dscp" configuration parameter to prioritize media packets in your internal network to provide better QoS.

  • How do I minimize echo and background noise while making calls using Browser SDK?

    We recommend using a USB headset with a built-in microphone and echo cancellation to help reduce background noise. If you use macOS, go to Sound settings, and under Input check the box to "Use ambient noise reduction." If you use Windows, see this article.

  • How do I send feedback on Browser SDK call quality to Plivo?

    Please use the submitCallQualityFeedback method to report audio and network-related issues to Plivo. We monitor all feedback and will take appropriate action. 

  • How do I hang up a call on a page reload or refresh?

    Use the command ‘onbeforeunload’ with native JavaScript listener to look for reload and refresh changes and call the Browser SDK's logout method. This will terminate any ongoing calls. More details about the logout method are available in our Browser SDK reference.

  • Should I call login() API if I’m auto-logged out?

    You don't need to call the login() API. Instead, listen for the onLogin event, as the websocket will autoconnect and log in again.

  • Why am I getting logged out of Browser SDK 2.0 without calling the logout method?

    You may be logged out for one of these reasons:

    • The internet connection is dropping packets continuously
    • The application is disconnected from the network
    • The system goes to sleep and disconnects network
    • The websocket fails to stay active due to network drops or latency
  • How do I detect audio and network issues in real time?

    You can use MediaMetrics events to detect network and audio issues. Refer to our Browser SDK reference guide for details.

  • How can I optimize call quality using Browser SDK 2.0?

    The quality of VoIP calls is influenced by a number of external factors, including the network the device is connected to and the device software and hardware. 

    Network characteristics

    VoIP calls involve the transmission of a continuous train of voice data packets. Due to network congestion, some packets may reach the recipient later than packets that were transmitted before them. This out-of-order receipt of packets, known as jitter, can make audio sound jumbled or robotic.  

    Jitter is measured in milliseconds of delay. Jitter values higher than 30 milliseconds (ms) on WebRTC calls can lead to poor audio quality. High jitter can also lead to jitter-induced packet loss, in which chunks of audio never arrive at their destination.

    The primary cause of jitter is network congestion, due to an overcrowded network with many devices consuming bandwidth at the same time. 

    Latency, in the context of VoIP calls, is the total spoken-to-heard delay in the transmission of audio. The major contributing factor to VoIP latency is the delay incurred in the transmission of voice packets from origin to destination. Network latency (measured as round trip time) of more than 300ms results in a noticeable audio lag on a call. Higher network latency can sometimes lead to crosstalk. 

    Plivo recommends

    To diminish jitter and latency, Plivo recommends:

    • Using a high-bandwidth fiber connection from a reputable internet provider. Dedicated business internet connections generally come with guaranteed SLAs on bandwidth and latency.

    • Using a physical Ethernet connection instead of Wi-Fi whenever possible.

    • If using Wi-Fi, limiting the number of devices connected on the same channel.

    • Using high-quality Wi-Fi routers built for enterprises or for real-time gaming. Look for routers that come with advanced QoS features.

    • Auditing your network firewall and NAT settings to check for transmission delays due to improper configuration.

    • Avoiding large data transfers on the same Wi-Fi network during calls.

    • Limiting bandwidth per connected device to ensure an even allocation of total available bandwidth.

    • Avoiding calls over cellular data connections (4G and older), as they are not optimized for low-latency traffic.

    • Setting the Differentiated Service Code Point (dscp) parameter of Plivo Browser SDK to "true." This setting informs network routers to prioritize voice packets over other network packets. Corresponding QoS configurations in the router may be also required. DSCP for WebRTC is supported by Chrome only.

    • Setting Plivo Media Server region selection in auto mode on Plivo Browser SDK. This ensures that calls get routed through the closest geographic PoP based on the device’s IP address.

    • Ensuring uplink and downlink bandwidth availability of at least 50Kbps for voice transmission. 

    • If operating in a low-bandwidth environment, cap the bandwidth to be consumed on calls using the maxAverageBitrate configuration parameter of the Plivo Browser SDK. 

    • Gracefully handling poor call quality experiences in real time by consuming mediaMetrics call quality events emitted by the Plivo Browser SDK during the course of calls. 

    • Submitting call quality feedback to Plivo programmatically from the Browser SDK or through the Send Feedback method of the Voice API. Your feedback allows Plivo to learn and optimize its network by identifying patterns across calls.

    Network firewalls

    Voice data on VoIP calls is transferred over UDP. Ensure that your network firewall allows transmission of UDP packets between client devices and the public internet.  

    If your firewall requires whitelisting of external IP addresses, ensure that Plivo’s SIP Signalling and Media Server IP addresses are whitelisted on your network firewall. 

    Device characteristics

    Several device characteristics also impact the quality of VoIP calls.

    Browser and OS

    Plivo Browser SDK uses WebRTC for voice calls. WebRTC is supported in the following browsers:

    • Chrome on Windows, Linux, macOS, and Android. Note that Chrome for iOS does not support WebRTC.

    • Firefox on Windows, Linux, macOS, and Android.  Note that Firefox for iOS does not support WebRTC.

    • Safari 11+ on iOS and macOS

    • New Microsoft Edge (based on Chromium) on Windows

    While WebRTC should be supported on these browsers, the Plivo Browser SDK v2 is tested and supported only in:

    • Chrome v55+ in desktop environments

    • Firefox v51+ in desktop environments

    • Microsoft Edge v79+ on Windows

    Plivo recommends customers use its native iOS and Android SDKs to build app-based calling functionality on mobile devices. Mobile browsers are required to be in the foreground for the entire duration of the call and lack call interruption handling for cellular calls received while on a browser call. Both these features are supported by the Plivo iOS and Android SDKs.

    Device hardware

    While most modern PC and smartphone devices are more than capable of handling VoIP media, incompatibilities between components such as network drivers and audio cards can result in unexpected issues with media handling. Attempting to reproduce issues on other devices should be a key step in your debugging process.

    Audio input and output devices

    Plivo recommends using quality headsets for browser-based calls. 

    Headsets minimize echo by providing acoustic isolation between the speaker and the microphone. High-quality VoIP headsets with noise-canceling features can enhance call quality in noisy environments by eliminating background sounds. 

    Wired headsets generally offer more stable sound quality than wireless or Bluetooth headsets. Wireless headsets are more prone to adapter and driver configuration issues, which can lead to static or white noise on calls. We recommend testing with a different headset, or with a PC's inbuilt mic and speaker, when troubleshooting such issues.

     

  • How do I reduce the CPU utilization of my application?

    You can initialize the SDK with the following parameters to improve CPU utilization. 

    1. Set  ‘permOnClick’ to true. This uses the microphone on demand to optimize CPU utilization. 
    2. Disable EchoCancallation and AutoGainControl in the ‘audioConstraints’ parameter. 

     Please refer to the initialization section in our WebSDK Getting Started guide for more details.

  • What browsers does BrowserSDK 2.0 support?

    BrowserSDK 2.0 uses webRTC APIs and currently supports the following browsers. 

    1. Chrome version 55 and above
    2. Firefox version 51 and above

    The SDK logs the event ‘onWebrtcNotSupported’ when you check if the browser can be used to make and receive calls. More details on this event are available in our WebSDK Getting Started guide.

  • What are AEC and AGC?

    AEC and AGC are configurations provided by the Chrome browser to adjust microphone levels and amplify the audio to make the call clear. AEC and AGC flags can be disabled in the browser SDK to improve CPU utilization as outlined in the WebSDK Getting Started Guide.

  • How can assess call quality?

    The four major call quality metrics are latency, jitter, packet loss, and mos-score. 

    Latency refers to the time it takes to transmit a packet from the source to the destination. When latency is high, users will experience a lag in their audio call. Calls tend to experience significant audio lags when the latency increases beyond 200ms.

    Packet loss is caused by network congestion. High loss of packets results in robotic or broken audio. Calls tend to experience issues when the packet loss is higher than 2%. 

    Jitter is caused when the packets arrive out of order. High measurements of jitter can cause muffled audio in voice calls. Calls tend to experience issues when jitter increases beyond 30ms.    

    How to enable MediaMetrics to access the call quality:

    • Go to the Plivo GitHub page to find an example of how to implement MediaMetrics on your application. If you want to see a MediaMetrics demo, use the online link. Select the network link conditioner for MacOs or Clumsy for Windows to simulate different network conditions. 
    • When you set “enableTracking” to “true” in an SDK configuration, you'll start to receive all network and audio-related WARNING  events under the "MediaMetrics" event listener.
    • Please refer to Plivo documentation to check the list of event names and their threshold limits.
  • Which languages should I use to write applications using Plivo SDK?

    Plivo web SDK is a JavaScript framework that allows you to embed voice call capability in your web apps. You can any standard web language to build a server-side app using our Web SDK.

    For Plivo’s mobile SDK, you should use Objective-C to embed VoIP capability into your mobile application. Mobile SDK is currently available for iOS-based devices (iPhone and iPad).

  • Where can I find examples of the Plivo Web SDK?

    Check out the Voice Chat API. It is a WebRTC-powered voice call app that uses the Plivo WebSDK. The app is open-sourced, so you can check out the source code, fork the repo and modify the app as you wish.

  • What is the Plivo SDK?

    SDK stands for Software Development Kit. The Plivo SDK is a Software Development Kit that enables you to embed voice call capability into your mobile and web applications. It provides a two-way audio capability for making and receiving voice calls. 

    We provide web and mobile SDKs. Our web SDK can be used to build web-based applications, such as a click-to-call button in the browser, real-time screen sharing, and a lot more. Our mobile SDK can be used to build IP-based voice call capabilities (VoIP) for your mobile applications.

  • What can I build with the Plivo SDK?

    With the Plivo Web and Mobile SDK, you can build all the common voice features, like IVR or conferencing. You can also write unique features such as click-to-call, audio recorders, in-app voice chat, or web and mobile softphone.

    Read how our customers have used the Plivo SDK here: https://www.plivo.com/customers/

    For more use cases, check out this page: https://www.plivo.com/use-cases/

  • The browser of my users doesn’t support WebRTC. Can I still use the Plivo Web SDK?

    No, you cannot. Plivo SDK calls are made via WebRTC. Plivo Web SDK V2 supports Google Chrome 55 and above and Firefox 51 and above.

    Please refer to our article, Does the Plivo Web SDK support WebRTC? for more information.