这份文档还在翻译中,预期年底前完成。欢迎您提供宝贵的意见及建议。
Overview
In this guide you learn how to add the Client SDK to your client-side JavaScript app.
Prerequisites
The Client SDK requires Node.js and NPM.
To add the Client SDK to your project
Navigate to your app
Open your terminal. If you have an existing app, navigate to its root. Otherwise, create a new directory for your project.
Add the Client SDK to your project
Install the Client SDK package
Add a default package.json
by running:
npm init -y
Install the Client SDK using npm
:
npm install nexmo-client -s
Import the Client SDK into your code
If your application is using ES6 module syntax, you can import the client module near the top of your application code:
import NexmoClient from 'nexmo-client';
If your application will run on a single page, you can load the module in your HTML using a script tag:
<script src="./node_modules/nexmo-client/dist/nexmoClient.js"></script>
Be sure to check that the path to nexmoClient.js
is correct for your project structure.
Load the Client SDK package
Load the Client SDK from a Content Delivery Network (CDN):
Inside the <head>
of your HTML file, add:
<!-- ******* Load nexmoClient from a CDN ****** -->
<script type="module" src="https://unpkg.com/nexmo-client@latest/dist/nexmoClient.js?module"></script>
Add the Client SDK into your code
Near the top of your application code, add:
//********* Get a reference to NexmoClient **********
const NexmoClient = window.NexmoClient;
Using the Client SDK in your app
Creating Users and JWTs
A JSON Web Token (JWT) is necessary to log in to your Vonage Application. The Client SDK cannot manage users nor generate JWTs, so you must choose a method of handling it on the backend:
- For onboarding or testing purposes, you can get your client-side app working before setting up a backend by generating a test JWT from the command line and hard-coding it in your client-side JavaScript.
-
For real world usage, you can deliver JWTs from the server using the Node or PHP backend SDKs, and set the
jwt
variable in your code by fetching that data:fetch('/getJwt') .then(results => results.json()) .then(data => { jwt = data.token; }) .catch(err => console.log(err));
Read more on generating JWTs in this article
Instantiate and log in the NexmoClient
No arguments are necessary to instantiate a new NexmoClient
, but you will need to pass your JWT as the argument to login()
.
let nexmo = new NexmoClient()
.login(jwt)
.then(app => console.log('Logged in to app', app))
.catch(err => console.log(err));
Client SDK analytics and usage data
To provide Vonage with more information to enable us to fix bugs and build features, you can optionally opt-in to our Client SDK analytics and usage data programme.
To enable analytics and data usage reporting, please set the enabled
parameter of log_reporter
to true
. The following code provides an example of this:
new NexmoClient({debug:true, log_reporter: {enabled: true}})
NOTE: This is opt-in only and turned off by default.
Conclusion
You added the Client SDK to your client-side JavaScript app and logged in to a NexmoClient
instance, which returned an Application
object. You can now use Application.newConversation()
to create a conversation, and then access the functionality of a Conversation
.
See also
- Data Center Configuration - this is an advanced optional configuration you can carry out after adding the SDK to your application.
Overview
In this guide you learn how to add the Client SDK to your Android app.
Prerequisites
The Client SDK requires a minimum Android API level of 23.
To add the Client SDK to your project
Open you Android project
Open your Android project codebase in your IDE.
Add dependencies
First, you need to add a custom Maven URL repository to your Gradle configuration. Add the following URL in your project-level build.gradle
file:
//...
allprojects {
repositories {
google()
jcenter()
maven("https://artifactory.ess-dev.com/artifactory/gradle-dev-local")
}
}
//...
allprojects {
repositories {
google()
jcenter()
maven {
url "https://artifactory.ess-dev.com/artifactory/gradle-dev-local"
}
}
}
Now add the Client SDK to your project. Add the following dependency in your app level build.gradle
file (typically app/build.gradle
):
dependencies {
implementation("com.nexmo.android:client-sdk:2.7.0")
}
dependencies {
implementation 'com.nexmo.android:client-sdk:2.7.0'
}
Set Java 1.8
Set Java 1.8 in your app level build.gradle
file (typically app/build.gradle
):
android {
// ...
kotlinOptions {
jvmTarget = JavaVersion.VERSION_1_8.toString()
}
compileOptions {
sourceCompatibility = JavaVersion.VERSION_1_8
targetCompatibility = JavaVersion.VERSION_1_8
}
}
android {
// ...
kotlinOptions {
jvmTarget = JavaVersion.VERSION_1_8.toString()
}
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
Add permissions
To use the In-App Voice features, add audio permissions using the following procedure:
- Add the required permissions to the
AndroidManifest.xml
file:
xml
<manifest ...>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
</manifest>
- For devices running Android version M (API level 23) or higher, you should request for the
RECORD_AUDIO
permission at runtime:
// this is the current activity
if (ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) != PackageManager.PERMISSION_GRANTED) {
ActivityCompat.requestPermissions(this, arrayOf(Manifest.permission.RECORD_AUDIO), 123)
}
// this is the current activity
if (ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) != PackageManager.PERMISSION_GRANTED) {
ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.RECORD_AUDIO}, 123);
}
Read more about requesting runtime permissions on Android here.
Using NexmoClient in your App
Building NexmoClient
Make sure to build the NexmoClient instance before using it.
NexmoClient.Builder().build(context)
NexmoClient.Builder().build(context);
Setting connection listener
Set NexmoConnectionListener
that will notify you on any changes on the connection to the SDK and the availability of its functionality:
NexmoClient().get().setConnectionListener { connectionStatus, connectionStatusReason ->
Log.d("TAG", "Connection status changed: $connectionStatus $connectionStatusReason")
}
NexmoClient().get().setConnectionListener { newConnectionStatus, connectionStatusReason ->
Log.d("TAG", "Connection status changed: " + connectionStatus + " " + connectionStatusReason);
}
Login NexmoClient
After initializing NexmoClient
, you need log in to it, using a jwt
user token. This is described in the topic on JWTs and ACLs.
Replace the token so as to authenticate the relevant user:
NexmoClient.get().login("JWT token")
NexmoClient.get().login("JWT token");
After the login succeeds, the logged in user is available via NexmoClient.get().getUser()
.
Conclusion
You added the Client SDK to your Android app, initialized it, and logged in to a NexmoClient
instance.
In production application good place to initialize NexmoClient
is custom Android Application class. You can later retrieve NexmoClient
instance using NexmoClient.get()
method and use additional NexmoClient
functionality.
See also
- Data Center Configuration - this is an advanced optional configuration you can carry out after adding the SDK to your application.
Overview
In this guide you learn how to add the Client SDK to your iOS app.
Prerequisites
To use the Vonage SDK for iOS, you need to have the following installed:
- Xcode 10 or later
- iOS 10.2 or later
Add the SDK to your iOS Project
Open Xcode with your iOS project.
You can either install the Client SDK directly, or via CocoaPods.
CocoaPods
-
Open your project's
PodFile
. If you don't have one already, open a terminal and run the following commands:$ cd 'Project Dir' $ pod init
Where
Project Dir
is the path to the parent directory of thePodFile
. -
Under your target add the
NexmoClient
pod. ReplaceTargetName
with your actual target name.target 'TargetName' do pod 'NexmoClient' end
Make sure the pod file has the public CocoaPod specs repository source.
-
Install the Pod by opening a terminal and running the following command:
$ cd 'Project Dir' $ pod update
Where
Project Dir
is the path to the parent directory of thePodFile
. Open the
xcworkspace
with Xcode and disablebitcode
for your target.In your code, import the
NexmoClient
library:
import NexmoClient
#import <NexmoClient/NexmoClient.h>;
Frameworks
Download the Client SDK then drag and drop the
NexmoClient.framework
folder into your project:Project explorer Turn on Embed & Sign for
NexmoClient.framework
in your target's settings:Embed & sign In your code, import the
NexmoClient
library:
import NexmoClient
#import <NexmoClient/NexmoClient.h>;
Add permissions
To use the in-app voice features, you need to add audio permissions:
In your
Info.plist
add a new row with 'Privacy - Microphone Usage Description' and a description for using the microphone. For example,Audio Calls
.In your code add a request for Audio Permissions:
import AVFoundation
func askAudioPermissions() {
AVAudioSession.sharedInstance().requestRecordPermission { (granted:Bool) in
NSLog("Allow microphone use. Response: %d", granted)
}
}
#import <AVFoundation/AVAudioSession.h>
- (void)askAudioPermissions {
if ([[AVAudioSession sharedInstance] respondsToSelector:@selector(requestRecordPermission:)])
{
[[AVAudioSession sharedInstance] requestRecordPermission: ^ (BOOL granted)
{
NSLog(@"Allow microphone use. Response: %d", granted);
}];
}
}
AppDelegate
is the best place to do this.
Using client in your app
Login
Create a NXMClient
object and login with a jwt
user token. If necessary, you can read more about generating the JWT.
let client = NXMClient.shared
client.setDelegate(self)
client.login(withAuthToken: "your token")
NXMClient *client = [NXMClient shared];
[self.client setDelegate:self];
[self.client loginWithAuthToken:@"your token"];
Note that self
should implement the NXMClientDelegate
protocol.
Connection status
On a successful login, the following delegate method is called with NXMConnectionStatusConnected
:
func client(_ client: NXMClient, didChange status: NXMConnectionStatus, reason: NXMConnectionStatusReason)
- (void)client:(nonnull NXMClient *)client didChangeConnectionStatus:(NXMConnectionStatus)status reason:(NXMConnectionStatusReason)reason
You can check if the connection status is connected with isConnected
:
var clientIsConnected: Bool = NXMClient.shared.isConnected()
BOOL clientIsConnected = [NXMClient.shared isConnected];
isConnected
will be the last connection status of the client if your app is suspended in the background. Therefore the value for isConnected
can be stale.
Get current user info
After the login succeeds, the logged in user will be available via:
let user = client.user
NXMUser *user = client.user;
Conclusion
You added the Client SDK to your iOS app, and logged in to a NXMClient
instance. You can now use the NXMClient
client in your app, and use the Client SDK functionality.
See also
- Data Center Configuration - this is an advanced optional configuration you can carry out after adding the SDK to your application.