diff --git a/OPENTOK_TO_VONAGE_MIGRATION.md b/OPENTOK_TO_VONAGE_MIGRATION.md new file mode 100644 index 000000000..815fff521 --- /dev/null +++ b/OPENTOK_TO_VONAGE_MIGRATION.md @@ -0,0 +1,91 @@ +# Migration guide from OpenTok .NET SDK to Vonage .NET SDK + +## Installation + +You can now interact with Vonage's Video API using the `Vonage` package rather than the `OpenTok` one. To do this, either look for "Vonage" is your package manager, or run the following command + +``` +dotnet add package Vonage +``` + +Note: not all the Video API features are yet supported in the `Vonage` package . There is a full list +of [Supported Features](#supported-features) later in this document. + +## Setup + +Whereas the `OpenTok` package used an `ApiKey` and `ApiSecret` for Authorization, the Video API implementation in the `Vonage` packages uses a JWT. The SDK handles JWT generation in the background for you, but will require an `ApplicationId` and `PrivateKey` as credentials in order to generate the token. +You can obtain these by setting up a Vonage Application, which you can create via the [Developer Dashboard](https://dashboard.nexmo.com/applications) (the Vonage Application is also where you can set other settings such as callback URLs, storage preferences, etc). + +These credentials are then loaded from your project settings. For more details on how to do that, feel free to take a look at the [Configuration](https://github.com/Vonage/vonage-dotnet-sdk#configuration) section. + +You can then use an instance of 'VonageClient' or `IVideoClient` to interact with the Video API via various methods, for example: + +- Create a Session + +```ruby +var session = await vonageClient.VideoClient.SessionClient.CreateSessionAsync(...); +// or +var session = await videoClient.SessionClient.CreateSessionAsync(...); +``` + +- Retrieve a List of Archive Recordings + +```ruby +var archives = await vonageClient.VideoClient.ArchiveClient.GetArchivesAsync(...); +// or +var archives = await videoClient.ArchiveClient.GetArchivesAsync(...); +``` + +## Changed Methods + +There are some changes to methods between the `OpenTok` SDK and the Video API implementation in the `Vonage` SDKs. + + +- Any operation will return a `Result`, indicating whether the operation is a success or a failure. For more details, feel free to take a look at the [Monads](https://github.com/Vonage/vonage-dotnet-sdk#monads) section. +- Creating a request will force you to rely on a builder (ex: `CreateSessionRequest.Build()...`) - all builders provide a fluent API to guide you through mandatory parameters, while proposing optional ones, before building the request using `.Create()`. +- Methods used to be available in both synchronous and asynchronous versions. The synchronous versions have been removed, leaving only the asynchronous one. If you still want to run that in a synchronous process, please consider using `Task.Wait()` or `Task.Result` on the returned `Task` object. +- Some methods have been renamed and/or moved, for clarity and/or to better reflect what the method does. These are + listed below: + +| OpenTok Method Name | Vonage Video Method Name | +|--------------------------------------|-----------------------------------------------------------| +| `OpenTok.GenerateToken` | `VideoTokenGenerator.GenerateToken` | +| `OpenTok.CreateSessionAsync` | `VonageClient.SessionClient.CreateSessionAsync` | +| `OpenTok.StartArchiveAsync` | `VonageClient.ArchiveClient.CreateArchiveAsync` | +| `OpenTok.StopArchiveAsync` | `VonageClient.ArchiveClient.StopArchiveAsync` | +| `OpenTok.GetArchiveAsync` | `VonageClient.ArchiveClient.GetArchiveAsync` | +| `OpenTok.DeleteArchiveAsync` | `VonageClient.ArchiveClient.DeleteArchiveAsync` | +| `OpenTok.ListArchivesAsync` | `VonageClient.ArchiveClient.GetArchivesAsync` | +| `OpenTok.AddStreamToArchiveAsync` | `VonageClient.ArchiveClient.AddStreamAsync` | +| `OpenTok.RemoveStreamToArchiveAsync` | `VonageClient.ArchiveClient.RemoveStreamAsync` | +| `OpenTok.GetStreamAsync` | `VonageClient.BroadcastClient.GetStreamAsync` | +| `OpenTok.ListStreamsAsync` | `VonageClient.BroadcastClient.GetStreamsAsync` | +| `OpenTok.ForceMuteStreamAsync` | `VonageClient.ModerationClient.MuteStreamAsync` | +| `OpenTok.ForceMuteAllAsync` | `VonageClient.ModerationClient.MuteStreamsAsync` | +| `OpenTok.ForceDisconnectAsync` | `VonageClient.ModerationClient.DisconnectConnectionAsync` | +| `OpenTok.StartBroadcastAsync` | `VonageClient.BroadcastClient.StartBroadcastAsync` | +| `OpenTok.StopBroadcastAsync` | `VonageClient.BroadcastClient.StopBroadcastAsync` | +| `OpenTok.GetBroadcastAsync` | `VonageClient.BroadcastClient.GetBroadcastAsync` | +| `OpenTok.SetBroadcastLayout` | `VonageClient.BroadcastClient.ChangeBroadcastLayoutAsync` | +| `OpenTok.SignalAsync` | `VonageClient.SignalingClient.SendSignalAsyncAsync` | +| `OpenTok.PlayDTMFAsync` | `VonageClient.SipClient.PlayToneIntoCallAsync` | +| `OpenTok.DialAsync` | `VonageClient.SipClient.InitiateCallAsynb` | + +## Supported Features + +The following is a list of Vonage Video APIs and whether the SDK provides support for them: + +| API | Supported? | +|---------------------------|:----------:| +| Session Creation | ✅ | +| Stream Management | ✅ | +| Signaling | ✅ | +| Moderation | ✅ | +| Archiving | ✅ | +| Live Streaming Broadcasts | ✅ | +| SIP Interconnect | ✅ | +| Account Management | ❌ | +| Experience Composer | ❌ | +| Audio Connector | ❌ | +| Live Captions | ❌ | +| Custom S3/Azure buckets | ❌ | \ No newline at end of file diff --git a/README.md b/README.md index f9f323dad..a42c614f7 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,10 @@ Changes in version 6.0.0 * Ncco now inherits from List, it no longer has the `Actions` property, to add an action use `ncco.Add(action);` * Strings with values "true" or "false" are now represented as `bool` in code +### Migrating from OpenTok for Video API + +If you are migrating from the OpenTok .NET SDK to the Vonage .NET SDK, please see the dedicated [migration guide](OPENTOK_TO_VONAGE_MIGRATION.md). + ### Targeted frameworks The SDK targets towards `netstandard2.0`. diff --git a/Vonage.sln b/Vonage.sln index f753ee3f7..6415a51e5 100644 --- a/Vonage.sln +++ b/Vonage.sln @@ -16,6 +16,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution pull_request_template.md = pull_request_template.md .whitesource = .whitesource cliff.toml = cliff.toml + OPENTOK_TO_VONAGE_MIGRATION.md = OPENTOK_TO_VONAGE_MIGRATION.md EndProjectSection EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Vonage", "Vonage\Vonage.csproj", "{41EF17C9-8D2E-4C7B-B2EE-3BD1A4CC1A1B}"