Skip to content

Latest commit

 

History

History
147 lines (113 loc) · 6.67 KB

README.md

File metadata and controls

147 lines (113 loc) · 6.67 KB
Raw

Vonage Server SDK for Kotlin (JVM)

Maven Central Build Status codecov SLOC Contributor Covenant License

This Kotlin SDK allows you to use Vonage APIs in any JVM-based application. You'll need to have created a Vonage account.

Supported APIs

Other SDKs

We also provide server SDKs in other languages:

We also offer client-side SDKs for iOS, Android and JavaScript. See all of our SDKs and integrations on the Vonage Developer portal.

Installation

Releases are published to Maven Central. Instructions for your build system can be found in the snippets section. They're also available from here. Release notes can be found in the changelog.

Build It Yourself

Note: We strongly recommend that you use a tool with dependency management, such as Maven or Gradle.

Alternatively you can clone the repo and build the JAR file yourself:

git clone git@github.com:vonage/vonage-kotlin-sdk.git
mvn install -P uberjar

The uberjar profile will create a JAR file with all dependencies included in the target directory at the root of the repo. You can then include this in your project's classpath.

Configuration

Typical Instantiation

For default configuration, you just need to specify your Vonage account credentials using API key and secret, private key and application ID or both. For maximum compatibility with all APIs, it is recommended that you specify both authentication methods, like so:

import com.vonage.client.kt.Vonage

val vonage = Vonage {
    apiKey(API_KEY); apiSecret(API_SECRET)
    applicationId(APPLICATION_ID)
    privateKeyPath(PRIVATE_KEY_PATH)
}

You can also use environment variables for convenience, by setting the following:

  • VONAGE_API_KEY - Your account API key
  • VONAGE_API_SECRET - Your account API secret
  • VONAGE_SIGNATURE_SECRET - (Advanced, optional) Signature secret for signed requests when using SMS API
  • VONAGE_APPLICATION_ID - UUID of the Vonage application you want to use
  • VONAGE_PRIVATE_KEY_PATH - Absolute path to the private key file for the application

and then instantiate the client with:

val vonage = Vonage { authFromEnv() }

Customization

You can configure the base URI (for example, to do integration tests) and HTTP request timeout with httpConfig during instantiation, like so:

val vonageClient = Vonage {
    authFromEnv()
    httpConfig {
        baseUri("http://localhost:8976")
        timeoutMillis(15000)
    }
}

Usage

You can find complete runnable code samples in the vonage-kotlin-code-snippets repository.

Frequently Asked Questions

Q: Why use this SDK instead of the Vonage Java Server SDK?

A: This Kotlin SDK is actually based on the Java SDK to improve the user experience in Kotlin. It adds syntactic sugar, so you can avoid the cumbersome builder pattern in favour of a more idiomatic DSL-like syntax, optional and named parameters with default values etc. whilst still reataining the strong typing offered by the Java SDK. Furthermore, you are more partially shielded from "platform types" (the !) so you have a better idea of what is and isn't nullable when creating requests.

Q: What is your policy on thread safety?

A: As with the Java Server SDK, only one thread should use the client at a time. If you would like to use the SDK in a multithreaded environment, create a separate instance of Vonage for each thread, or use a ThreadLocal instance.

Contribute!

We ❤️ contributions to this library!

It is a good idea to talk to us first if you plan to add any new functionality. Otherwise, bug reports, bug fixes and feedback on the library are always appreciated.

Contact

Slack Twitter