Android integration via SDK

Ramp Android SDK is a library that allows you to easily integrate Ramp into your Android app and communicate with it.

Overview

In this tutorial, we'll install the SDK via Gradle and initialize it with configuration data. We'll also go over implementing callbacks for events sent by Ramp.

Installing the Gradle Plugin

To install the Ramp Android SDK, add its repository in your root build.gradle at the end of repositories:

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

Add the dependency in your build.gradle file:

dependencies {
    implementation 'com.github.RampNetwork:ramp-sdk-android:3.+'
}

Initializing the SDK

Go to an Activity or a Fragment in your directory where you want to start a transaction with Ramp. Add the following import statements to the top of the file:

import network.ramp.sdk.events.model.Purchase
import network.ramp.sdk.facade.Config
import network.ramp.sdk.facade.RampCallback
import network.ramp.sdk.facade.RampSDK

After that, you need to initialize the SDK with your activity context.

class MainActivity : AppCompatActivity() {

    private lateinit var rampSdk: RampSDK

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        rampSdk = RampSDK()
        // ...
    }
    // ...
}

Filling the configuration object with your data

Ramp widget allows you to provide some useful parameters before displaying it. Most of the parameters are optional. You can set options such as user wallet address, desired cryptocurrency and crypto amount, etc. In order to do so, we need to add those parameters to a Config object provided by SDK.

val config = Config(
    hostLogoUrl = "https://assets.ramp.network/misc/test-logo.png",
    hostAppName = "My App",
    hostApiKey = "your_host_api_key",
    userAddress = "user_blockchain_address",
    // optional, skip this param to use the production URL
    url = "https://app.demo.ramp.network",
    swapAsset = "ETH_ETH",
    offrampAsset = "ETH_ETH",
    fiatCurrency = "USD",
    fiatValue = "10",
    userEmailAddress = "test@example.com"
    enabledFlows = setOf(Flow.ONRAMP, Flow.OFFRAMP)
)

You can find the description of all available parameters in our documentation.

Implementing callbacks

Create a callback object RampCallback to handle transaction events that you can react to in your app.

Methods you can get by implementing this object:

• onPurchaseCreated(purchase: Purchase, purchaseViewToken: String, apiUrl: String) is called when a purchase is created, and returns a Purchase object, containing all its parameters. All fields of are described in the documentation here.
• onOfframpSaleCreated(sale: OfframpSale, saleViewToken: String, apiUrl: String) is called when a off-ramp sale is created, and returns a OfframpSale object, containing all its parameters. All fields of are described in the documentation here.
• offrampSendCrypto(assetInfo: AssetInfo, amount: String, address: String) is called when a user clicks Send with your wallet button to initialize crypto transfer.
• onWidgetClose() is called when Ramp finishes the flow and can be closed, or user closed it manually.

val callback = object: RampCallback {

    override fun onPurchaseCreated(
        purchase: Purchase,
        purchaseViewToken: String,
        apiUrl: String
    ) {
        // ...
    }

    fun onOfframpSaleCreated(
        sale: OfframpSale,
        saleViewToken: String,
        apiUrl: String
    ) {
        // ...
    }

    fun offrampSendCrypto(
        assetInfo: AssetInfo,
        amount: String,
        address: String
    ) {
        // ...
    }

    override fun onWidgetClose() {
        // ...
    }
}

Starting the widget

That's it, now you just need to run the startTransaction(activity: Activity, config: Config, callback: RampCallback) method to open the Ramp widget. This method takes config object that you created above.

rampSdk.startTransaction(activity, config, callback)

Example & Demo App

A full code example for a basic integration can be found below. You can find a demo integration showing how to integrate the Ramp SDK for Android on our Github.

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import kotlinx.android.synthetic.main.activity_main.*
import network.ramp.sdk.events.model.Purchase
import network.ramp.sdk.facade.Config
import network.ramp.sdk.facade.RampCallback
import network.ramp.sdk.facade.RampSDK


class MainActivity : AppCompatActivity() {

    // initialize the SDK
    private lateinit var rampSdk: RampSDK

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        rampSdk = RampSDK()

        button.setOnClickListener {
            // fill configuration object with your data
            val config = Config(
                hostLogoUrl = "https://assets.ramp.network/misc/test-logo.png",
                hostAppName = "My App",
                hostApiKey = "your_host_api_key",
                userAddress = "0x4b7f8e04b82ad7f9e4b4cc9e1f81c5938e1b719f",
                url = "https://app.demo.ramp.network",
                swapAsset = "ETH_ETH",
                offrampAsset = "ETH_ETH",
                fiatCurrency = "USD",
                fiatValue = "10",
                userEmailAddress = "test@example.com"
                enabledFlows = setOf(Flow.ONRAMP, Flow.OFFRAMP)
                useSendCryptoCallback = true
            )

            // implement callbacks
            val callback = object : RampCallback {
                override fun onPurchaseCreated(
                    purchase: Purchase,
                    purchaseViewToken: String,
                    apiUrl: String
                ) {
                    ...
                }

                override fun onOfframpSaleCreated(
                    sale: OfframpSale,
                    saleViewToken: String,
                    apiUrl: String
                ) {
                    // ...
                }

                override fun offrampSendCrypto(
                    assetInfo: AssetInfo,
                    amount: String,
                    address: String
                ) {
                    // custom view to initialize the transfer should be presented here
                    rampSdk.onOfframpCryptoSent(txHash)
                }

                override fun onWidgetClose() {
                    ...
                }
            }

            // start Ramp
            rampSdk.startTransaction(activity, config, callback)
        }
    }
}

note

If you want to provide the best off-ramping (selling crypto) experience to your users, we recommend to take advantage of the Native Flow. Implementation of the native flow may be required in some native mobile apps. You can see more details here.