Introduction to Connect

​

Introduction

• Connect is the client-side component that your users will interact with in order to link their accounts to Gandalf and allow you to access their data.
• Connect will handle credential validation, multi-factor authentication, and error-handling for every service that Gandalf supports. You can use Connect in any kind of application (web or mobile) - it’s as simple as just adding a link to your app.
• Connect is an App Clip & Instant App. These let users enjoy native app experiences without the need to download a full app. Learn more on Apple Developers & Android Developers

To try Connect, check out the Heimdall Example.

​

Connect Flow

The diagram below shows how Connect is used to obtain a dataKey, which is used server-side to request data.

The flow begins when your user wants to link their account/data to your application.

1. Open Connect for your users by navigating to the Connect URL. Pass your publicKey, redirectUrl and the data source(s) you want to read data from.
2. After your user is done linking their account(s), Connect will navigate to your redirectUrl with a query parameter called dataKey.
3. This dataKey will be used to make requests to the Sauron API

​

Connect Helper Package

We provide packages to make it easy to generate a valid Connect URL. The Connect helper handles parameter validations automagically!

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "YourProjectName",
    dependencies: [
        .package(url: "https://github.com/gandalf-network/connect-ios-sdk.git", .upToNextMajor(from: "1.0.0"))
    ],
    targets: [
        .target(
            name: "YourTargetName",
            dependencies: ["GandalfConnect"]
        )
    ]
)

import GandalfConnect

let services: InputData = [
    "uber": .service(Service(traits: ["rating"], activities: ["trip"]))
]

let input = ConnectInput(
    publicKey: "yourPublicKey",
    redirectURL: "https://example.com",
    services: services
)

let connect = Connect(input: input)

do {
    let generatedURL = try await connect.generateURL()
    print("Generated URL: \(generatedURL)")
} catch {
    print("Error generating URL: \(error)")
}

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "YourProjectName",
    dependencies: [
        .package(url: "https://github.com/gandalf-network/connect-ios-sdk.git", .upToNextMajor(from: "1.0.0"))
    ],
    targets: [
        .target(
            name: "YourTargetName",
            dependencies: ["GandalfConnect"]
        )
    ]
)

import GandalfConnect

let services: InputData = [
    "uber": .service(Service(traits: ["rating"], activities: ["trip"]))
]

let input = ConnectInput(
    publicKey: "yourPublicKey",
    redirectURL: "https://example.com",
    services: services
)

let connect = Connect(input: input)

do {
    let generatedURL = try await connect.generateURL()
    print("Generated URL: \(generatedURL)")
} catch {
    print("Error generating URL: \(error)")
}

npm i @gandalf-network/connect

// Typescript && ESModules
import Connect from '@gandalf-network/connect'
import { Platform } from "@gandalf-network/connect/components";

// CommonJS
const Connect = require("@gandalf-network/connect");
const { Platform } = require("@gandalf-network/connect/components");

// Initialize Connect
const connect = new Connect({
    publicKey: "YOUR_PUBLIC_KEY",
    redirectURL: "YOUR_REDIRECT_URL",
    // The platform defaults to IOS but could be ANDROID or UNIVERSAL
    platform: Platform.ANDROID,
    services:
    {
        uber: {
            traits: ["rating"],
            activities: ["trip"],
        },
        gandalf: {
            traits: ["email"]
        }
    }
})

try {
// Generate the Connect URL
    const connectUrl = await connect.generateURL()

    // Use the URL as needed
    console.log('Generated Connect URL:', connectUrl)

    // If you want to display a QR Code instead:
    const qrCodeDataUrl = await connect.generateQRCode()
} catch (error) {
    // handle error
}

<img src={{qrCodeDataUrl}} alt="Connect QR Code"/>

repositories {
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.gandalf-network:connect-kotlin-sdk:1.0.0")
}

repositories {
    mavenCentral()
    maven {
        url 'https://jitpack.io'
    }
}

dependencies {
    implementation 'com.github.gandalf-network:connect-kotlin-sdk:1.0.0'
}

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.gandalf-network</groupId>
        <artifactId>connect-kotlin-sdk</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

// The Connect class
import com.gandalf.connect.Connect

// Useful Types
import com.gandalf.connect.types.ConnectInput
import com.gandalf.connect.types.InputData
import com.gandalf.connect.types.Service

val publicKey = ""
val redirectURL = "https://example.com"
val services: InputData = mutableMapOf(
    "uber" to Service(traits = listOf("rating"), activities = listOf("trip"))
)

val connectInput = ConnectInput(publicKey, redirectURL, services)

val connect = Connect(connectInput)

runBlocking {
    try {
        val generatedURL = connect.generateURL()
        println("Generated URL: $generatedURL")
    } catch (e: Exception) {
        println("Error: ${e.message}")
    }
}

​

Get Data Key

After your user is done linking their accounts, Connect will navigate to your redirectUrl with a query parameter called dataKey.

You can use the packages to get the dataKey easily.

do {
    let dataKey = try Connect.getDataKeyFromURL(redirectURL: "https://example.com?dataKey=testDataKey")
    print("Data Key: \(dataKey)")
} catch {
    print("Error extracting data key: \(error)")
}

Proceed by sending the dataKey to your server, where you can securely request the data you seek.