Standard

Follow this guide to do a standard integration of Vessel within your app:

Minimum requirements:

Unity

• Unity version 2019.4+

• Unity IAP 4.+

Android

• Android API level 24 (Android OS 7.0) or higher.

iOS

• iOS 13.0 or higher

Integrate the Vessel SDK

Follow one of the following sets of instructions to integrate Vessel SDK into your project:

Unity

1. Download the latest version of Unity SDK from https://artifacts.openvessel.io/unity/OpenVessel-1.17.1.unitypackage

2. In Unity, select Assets > Import Package > Custom Package…

3. Choose the Unity Plugin file you downloaded.

4. In the Import Unity Package dialog, click Import.

Android

Add the following to your app-level build.gradle file:

repositories {
    google()
    mavenCentral()
    jcenter()
    maven {
        url "https://artifacts.openvessel.io/maven/"
    }
}
dependencies {
    implementation 'io.openvessel:sdk:1.17.+'
}

iOS (Cocoapods)

1. Add the following lines to your Podfile:

source 'https://cdn.cocoapods.org' 
source 'https://github.com/OpenVesselIO/Wallet-Pods-iOS.git'
⋮
target '<YOUR PROJECT>' do
  pod 'OpenVesselSDK', '~> 1.17.1'
end

2. Add vesselwa scheme to your Info.plist

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>vesselwa</string>
</array>

When you want to update the SDK version, you need to run the command below.

Unity

iOS

Run pod update in a root directory of an iOS project.

Android

1) Assets > External Dependency Manager > Android > Delete Resolved Libraries

2) Assets > External Dependency Manager > Android Resolver > Force Resolve

Android

System

Clear the Gradle cache in your system in the following paths:

• On Windows: %USERPROFILE%\.gradle\caches

• On Mac / UNIX: ~/.gradle/caches/

IntelliJ IDEA

Click the refresh arrows in the Gradle tool window.

Android Studio

Click the elephant + arrow icon in the toolbar.

iOS

Run pod update in a root directory of an iOS project.

Import Packages

Unity

using OVSdk;

Android

import io.openvessel.wallet.sdk.VesselEnvironment;
import io.openvessel.wallet.sdk.VesselSdk;

iOS

#import <OpenVessel/OpenVessel.h>

Staging Environment

AppLovin recommends that you test your integration in the staging environment. Before you release your project, make sure to change your release version so that it points to production instead. You can point your project to the staging environment with code like the following:

Unity

OVSdk.Sdk.Environment = VesselEnvironment.Staging;

Android

VesselSdk.getInstance( activity )
         .setEnvironment(VesselEnvironment.STAGING);

iOS

[[OVLSdk sharedInstance] setEnvironment: OVLEnvironmentStaging]; 

Read the Staging Environment page for more information about environment management:

Staging Environment

Add a Connect Listener

Add a listener that is notified when your application connects to the Vessel Wallet:

Unity

OVSdk.AppConnectManagerCallbacks.OnStateUpdated += HandleStateUpdate;

// Listener definition
private void HandleStateUpdate(OVSdk.AppConnectState state)
{
    // ...
}

Android

VesselSdk.getInstance( activity )
         .getAppConnectManager()
         .setAppConnectListener( listener );
         
// Listener definition
public void onStateUpdated(final AppConnectManager manager)
{
    final AppConnectState newState = manager.getState();
    // ...
}

iOS

[[OVLSdk sharedInstance].appConnectManager setDelegate: delegate
                           delegateQueue: dispatch_get_main_queue()
];

// Delegate definition
- (void)appConnectManagerDidUpdateState:(OVLAppConnectManager *)appConnectManager
{
    OVLAppConnectState * newState = appConnectManager.state;
    // ...
}

The AppConnectState object has the following attributes:

Name	Type	Description
Status	AppConnectStatus	The current connection status (see below).
WalletAddress	string	The address of the connected user wallet. This is null if the wallet is not connected
AccessToken	string	JWT token of user session.

AccessToken example

eyJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJodHRwczovL3dhbGxldC5zdGFnZS5vcGVudmVzc2VsLmlvIiwiZXhwIjoxNjc2NTU0MTkyLCJzdWIiOiJ1YTczOTUzOTgxZWE0NDQzMmZmMTc4NWNiYmI2MTYwMDI3IiwiYXVkIjoiYSIsImlhdCI6MTY3NjUzNjE5MiwiciI6IlRYIiwic2kiOiJ1czAxNjA1M2YwZGFiMjQzM2ViNmM0ZDEwYTU1ZjMzNzlkIiwic2UiOjE2NzY1MzYxOTIsIndhIjoiMHhlMTE3MTVmYTI4MTI2Y2Y5ZjAwYjEwYzQxYTcyMDY0ZWQzZGY0ZDk3Iiwid3QiOiJDVVNUT0RJQUwiLCJ2ZXJpZmllZCI6IlAiLCJzIjoiV0VCOnBvcnRhbC5zdGFnZS5vcGVudmVzc2VsLmlvIiwibCI6ImVuLUdCIiwidSI6IiIsImt2IjoyLCJ0dWFpZCI6InVhNzM5NTM5ODFlYTQ0NDMyZmYxNzg1Y2JiYjYxNjAwMjcifQ.UEg9ycYLJb-2BRiBzfniMQNpTpGkIpbtUa_ZjEIsi6KPmLRJ2FiOg3CwCaFFbAE16tOc8AzHgM0463TnFTqjOg

Decoding

{
  "iss": "https://wallet.stage.openvessel.io",
  "exp": 1676554192,
  "sub": "ua73953981ea44432ff1785cbbb6160027",
  "aud": "a",
  "iat": 1676536192,
  "r": "TX",
  "si": "us016053f0dab2433eb6c4d10a55f3379d",
  "se": 1676536192,
  "wa": "0xe11715fa28126cf9f00b10c41a72064ed3df4d97",
  "wt": "CUSTODIAL",
  "verified": "P",
  "s": "WEB:portal.stage.openvessel.io",
  "l": "en-GB",
  "u": "",
  "kv": 2,
  "tuaid": "ua73953981ea44432ff1785cbbb6160027"
}

wa - User wallet address
u - In-game user id
iss - Environment
verified - Verification type(P - phone number; E - email; P,E - both verified)

The AppConnectStatus enum has the following possible values:

Unity

Type	Description
NotInitialized	SDK is not initialized. This is the initial status.
Disconnected	The wallet is not connected yet or is disconnected.
Connected	The wallet is connected.
ErrorCanceled	A user has explicitly canceled the app connect operation.
ErrorDeclined	A user declined an app connect operation or the operation is expired.
ErrorWalletNotInstalled	Vessel Wallet is not installed on user’s device.
Error	A non-recoverable error has occurred.

Android

Type	Description
NOT_INITIALIZED	SDK is not initialized. This is the initial status.
DISCONNECTED	The wallet is not connected yet or is disconnected.
CONNECTED	The wallet is connected.
ERROR_CANCELED	A user has explicitly canceled the app connect operation.
ERROR_DECLINED	A user declined an app connect operation or the operation is expired.
ERROR_WALLET_NOT_INSTALLED	Vessel Wallet is not installed on user’s device.
ERROR	A non-recoverable error has occurred.

iOS

Type	Description
OVLAppConnectStatusNotInitialized	SDK is not initialized. This is the initial status.
OVLAppConnectStatusDisconnected	The wallet is not connected yet or is disconnected.
OVLAppConnectStatusConnected	The wallet is connected.
OVLAppConnectStatusCancelled	A user has explicitly canceled the app connect operation.
OVLAppConnectStatusDeclined	A user declined an app connect operation or the operation is expired.
OVLAppConnectStatusWalletNotInstalled	Vessel Wallet is not installed on user’s device.
OVLAppConnectStatusError	A non-recoverable error has occurred.

Initialize the SDK

You must initialize the Vessel SDK before you can use it. Initializing the SDK triggers the first notification of the App Connect Listener that contains the initial state.

Important: You must pass a unique in-game user ID during initialization.

Important: You need to initialize the SDK at launch of your application to track wallet connections accurately.

Use the following code snippet below to initialize our SDK:

Unity

OVSdk.Sdk.Initialize("in-game-user-id");

Android

VesselSdk.getInstance( activity )
         .initialize("in-game-user-id");

iOS

[[[OVLSdk sharedInstance] startWithUserId: @"in-game-user-id"];

In-game user ID

You need to pass your own in-game user ID or you need to create a user specific ID. This can be any string and it isn't something provided by Vessel.

Connect Wallet

When your game connects to the wallet application, this opens up our Vessel wallet app and prompts the user to confirm the connection with your game.

Vessel delivers the result of this app connect operation via the App Connect Listener.

Important: You must pass a unique in-game user ID when connecting the wallet.

The code snippet below will invoke the pre-built UI provided by the Vessel SDK:

Unity

OVSdk.Sdk.AppConnectManager.LoadConnectWalletView("in-game-user-id");

Android

VesselSdk.getInstance( activity )
         .getAppConnectManager()
         .startConnectActivity( "in-game-user-id", activity )

iOS

[[[OVLSdk sharedInstance] appConnectManager]
                 presentConnectFromViewController: currentController
                 withUserId: @"in-game-user-id"
                 animated: YES];

If you want to use your own UI to connect wallet, please refer to Connect Wallet - Native section.

Show User Wallet

After your application connects to the user’s wallet, you can show an In-app WebView that allows the user to inspect and interact with their wallet.

Unity

OVSdk.Sdk.WalletPresenter.ShowWallet();

Android

final VesselSdk sdk = VesselSdk.getInstance( currentActivity );
sdk.getWalletPresenter().showWallet( currentActivity );

iOS

[[[OVLSdk sharedInstance] presentationController] presentWalletFromViewController:viewController 
                                                  animated:YES
];

Show the Game/Collection/Token Page

You can render your Vessel Game Store, Collection, and Token page within your application in a WebView using the following code below:

Unity

// Show the game level info
// fqgn: Fully Qualified Game Name ("com.studio.game")
OVSdk.Sdk.WalletPresenter.ShowGame(fqgn);

// Show the collection level info
// fqcn: Fully Qualified Collection Name ("com.studio.game.collection")
OVSdk.Sdk.WalletPresenter.ShowCollection(fqcn);

// Show the token level info
// fqtn: Fully Qualified Token Name ("com.studio.game.collection.token")
OVSdk.Sdk.WalletPresenter.ShowToken(fqtn);

Android

final VesselSdk sdk = VesselSdk.getInstance( currentActivity );

// Show the game level info
// fqgn: Fully Qualified Game Name ("com.studio.game")
sdk.getWalletPresenter().showGame( fqgn, currentActivity );

// Show the collection level info
// fqcn: Fully Qualified Collection Name ("com.studio.game.collection")
sdk.getWalletPresenter().showCollection( fqcn, currentActivity );

// Show the token level info
// fqtn: Fully Qualified Token Name ("com.studio.game.collection.token")
sdk.getWalletPresenter().showToken( fqtn, currentActivity );

iOS

// Show the game level info
// fqgn: Fully Qualified Game Name ("com.studio.game")
[[[OVLSdk sharedInstance] presentationController] presentGame:fqgn fromViewController:viewController animated:YES];

// Show the collection level info
// fqcn: Fully Qualified Collection Name ("com.studio.game.collection")
[[[OVLSdk sharedInstance] presentationController] presentCollection:fqcn fromViewController:viewController animated:YES];

// Show the token level info
// fqtn: Fully Qualified Token Name ("com.studio.game.collection.token")
[[[OVLSdk sharedInstance] presentationController] presentToken:fqtn fromViewController:viewController animated:YES];

Callbacks for opening/closing the WebView

Unity

OVSdk.WalletPresenterCallbacks.OnWalletShow += HandleWalletShow;
OVSdk.WalletPresenterCallbacks.OnWalletDismiss += HandleWalletDismiss;

private void HandleWalletShow()
{
    // a wallet is about to present
}

private void HandleWalletDismiss()
{
    // a wallet is about to dismiss
}

Android

VesselSdkImpl.getInstance( activity )
             .getWalletPresenter()
             .setListener( listener );
        
// Listener definition
@Override
public void onWalletShow()
{
    // a wallet is about to present
}

@Override
public void onWalletDismiss()
{
    // a wallet is about to dismiss
}

iOS

OVLSdk.sharedInstance.presentationController.delegate = delegate;

// Delegate definition
- (void)presentationControllerWillPresentWallet:(OVLPresentationController *)presentationController
{
    // a wallet is about to present
}

- (void)presentationControllerWillDismissWallet:(OVLPresentationController *)presentationController
{
    // a wallet is about to dismiss
}

Show the Wallet/Game/Collection/Token Page in the Vessel application

You can render your Vessel Wallet, Game, Collection, and Token page directly in the Vessel application. If the Vessel application is not installed on the device, you will be offered with installing it from the store page.

Unity

// Show the wallet info
OVSdk.Sdk.WalletPresenter.OpenWalletApplication();

// Show the game level info
// fqgn: Fully Qualified Game Name ("com.studio.game")
OVSdk.Sdk.WalletPresenter.OpenGameInWalletApplication(fqgn);

// Show the collection level info
// fqcn: Fully Qualified Collection Name ("com.studio.game.collection")
OVSdk.Sdk.WalletPresenter.OpenCollectionInWalletApplication(fqcn);

// Show the token level info
// fqtn: Fully Qualified Token Name ("com.studio.game.collection.token")
OVSdk.Sdk.WalletPresenter.OpenTokenInWalletApplication(fqtn);

Android

final VesselSdk sdk = VesselSdk.getInstance(currentActivity);

// Show the wallet level info
sdk.getWalletPresenter().openWalletApplication(currentActivity);

// Show the game level info
// fqgn: Fully Qualified Game Name ("com.studio.game")
sdk.getWalletPresenter().openGameInWalletApplication(fqgn, currentActivity);

// Show the collection level info
// fqcn: Fully Qualified Collection Name ("com.studio.game.collection")
sdk.getWalletPresenter().openCollectionInWalletApplication(fqcn, currentActivity);

// Show the token level info
// fqtn: Fully Qualified Token Name ("com.studio.game.collection.token")
sdk.getWalletPresenter().openTokenInWalletApplication(fqtn, currentActivity);

iOS

// Show the wallet info
[[[OVLSdk sharedInstance] presentationController] openWalletApplication];

// Show the game level info
// fqgn: Fully Qualified Game Name ("com.studio.game")
[[[OVLSdk sharedInstance] presentationController] openGameInWalletApplication:fqgn];

// Show the collection level info
// fqcn: Fully Qualified Collection Name ("com.studio.game.collection")
[[[OVLSdk sharedInstance] presentationController] openCollectionInWalletApplication:fqcn];

// Show the token level info
// fqtn: Fully Qualified Token Name ("com.studio.game.collection.token")
[[[OVLSdk sharedInstance] presentationController] openTokenInWalletApplication:fqtn];

Confirm the transaction

You can confirm the transaction detail in the Vessel wallet app.

Unity

OVSdk.Sdk.WalletPresenter.ConfirmTransactionInWalletApplication(transactionId);

Android

final VesselSdk sdk = VesselSdk.getInstance( currentActivity );

sdk.getWalletPresenter().confirmTransactionInWalletApplication(transactionId, currentActivity);

iOS

[OVLSdk.sharedInstance.presentationController confirmTransactionInWalletApplication:transactionId];