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.

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.
After your user is done linking their account(s), Connect will navigate to your redirectUrl with a query parameter called dataKey.
This dataKey will be used to make requests to the Sauron API

Once your end-user signs into a data source like Netflix or Amazon, they won’t need to sign in again. Their session stays active, just like in a browser.

Connect Helper Package

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

Install Using Swift Package Manager in Xcode

Open your project in Xcode.
Go to File > Add Packages....
Enter the repository URL: https://github.com/gandalf-network/connect-ios-sdk.git.
Choose the version rule (e.g., “Up to Next Major”) and click Add Package.
Select the GandalfConnect package for your target.

Or Update Package.swift

// 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"]
        )
    ]
)

Then, run swift package update to fetch the dependency.

Usage

Import the package

import GandalfConnect

Initialization

Create an instance of ConnectInput with the necessary details:

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

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

Initialize the Connect class:

let connect = Connect(input: input)

Generating URL

To generate a URL, call the generateURL method:

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

Read more on Github.

Install Using Swift Package Manager in Xcode

Open your project in Xcode.
Go to File > Add Packages....
Enter the repository URL: https://github.com/gandalf-network/connect-ios-sdk.git.
Choose the version rule (e.g., “Up to Next Major”) and click Add Package.
Select the GandalfConnect package for your target.

Or Update Package.swift

// 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"]
        )
    ]
)

Then, run swift package update to fetch the dependency.

Usage

Import the package

import GandalfConnect

Initialization

Create an instance of ConnectInput with the necessary details:

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

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

Initialize the Connect class:

let connect = Connect(input: input)

Generating URL

To generate a URL, call the generateURL method:

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

Read more on Github.

Install

npm i @gandalf-network/connect

Usage

Import the package

// 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");

Connect


// 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
}

Display the QR code using the qrCodeDataUrl

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

Read more on Github.

Install with Gradle

To integrate GandalfConnect into your project, add it to your build.gradle.kts or build.gradle file:

build.gradle.kts

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

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

build.gradle

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

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

Install with Maven

To integrate GandalfConnect into your project, add it to your pom.xml file:

build.gradle.kts

<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>

Usage

Importing the Library

In your Kotlin file where you want to use GandalfConnect, import the library:

// 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

Connect

Create an instance of ConnectInput with the necessary details:

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)

Initialize the Connect class:

val connect = Connect(connectInput)

To generate a URL, call the generateURL method:

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

Read more on Github.

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.

Alternatively, your redirectURL could be a server-side endpoint. You can get the dataKey directly from your application’s server.

On this page

Introduction
Connect Flow
Connect Helper Package
Get Data Key

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.

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.
After your user is done linking their account(s), Connect will navigate to your redirectUrl with a query parameter called dataKey.
This dataKey will be used to make requests to the Sauron API

Once your end-user signs into a data source like Netflix or Amazon, they won’t need to sign in again. Their session stays active, just like in a browser.

Connect Helper Package

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

Install Using Swift Package Manager in Xcode

Open your project in Xcode.
Go to File > Add Packages....
Enter the repository URL: https://github.com/gandalf-network/connect-ios-sdk.git.
Choose the version rule (e.g., “Up to Next Major”) and click Add Package.
Select the GandalfConnect package for your target.

Or Update Package.swift

// 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"]
        )
    ]
)

Then, run swift package update to fetch the dependency.

Usage

Import the package

import GandalfConnect

Initialization

Create an instance of ConnectInput with the necessary details:

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

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

Initialize the Connect class:

let connect = Connect(input: input)

Generating URL

To generate a URL, call the generateURL method:

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

Read more on Github.

Install Using Swift Package Manager in Xcode

Open your project in Xcode.
Go to File > Add Packages....
Enter the repository URL: https://github.com/gandalf-network/connect-ios-sdk.git.
Choose the version rule (e.g., “Up to Next Major”) and click Add Package.
Select the GandalfConnect package for your target.

Or Update Package.swift

// 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"]
        )
    ]
)

Then, run swift package update to fetch the dependency.

Usage

Import the package

import GandalfConnect

Initialization

Create an instance of ConnectInput with the necessary details:

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

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

Initialize the Connect class:

let connect = Connect(input: input)

Generating URL

To generate a URL, call the generateURL method:

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

Read more on Github.

Install

npm i @gandalf-network/connect

Usage

Import the package

// 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");

Connect


// 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
}

Display the QR code using the qrCodeDataUrl

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

Read more on Github.

Install with Gradle

To integrate GandalfConnect into your project, add it to your build.gradle.kts or build.gradle file:

build.gradle.kts

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

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

build.gradle

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

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

Install with Maven

To integrate GandalfConnect into your project, add it to your pom.xml file:

build.gradle.kts

<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>

Usage

Importing the Library

In your Kotlin file where you want to use GandalfConnect, import the library:

// 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

Connect

Create an instance of ConnectInput with the necessary details:

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)

Initialize the Connect class:

val connect = Connect(connectInput)

To generate a URL, call the generateURL method:

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

Read more on Github.

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.

Alternatively, your redirectURL could be a server-side endpoint. You can get the dataKey directly from your application’s server.

On this page

Introduction
Connect Flow
Connect Helper Package
Get Data Key

​Introduction

​Connect Flow

​Connect Helper Package

​Install Using Swift Package Manager in Xcode

​Or Update Package.swift

​Usage

​Import the package

​Initialization

​Generating URL

​Install Using Swift Package Manager in Xcode

​Or Update Package.swift

​Usage

​Import the package

​Initialization

​Generating URL

​Install

​Usage

​Import the package

​Connect

​Install with Gradle

​build.gradle.kts

​build.gradle

​Install with Maven

​build.gradle.kts

​Usage

​Importing the Library

​Connect

​Get Data Key

Get Started

Concepts

Guides

Examples

Data Sources

Schema

​Introduction

​Connect Flow

​Connect Helper Package

​Install Using Swift Package Manager in Xcode

​Or Update Package.swift

​Usage

​Import the package

​Initialization

​Generating URL

​Install Using Swift Package Manager in Xcode

​Or Update Package.swift

​Usage

​Import the package

​Initialization

​Generating URL

​Install

​Usage

​Import the package

​Connect

​Install with Gradle

​build.gradle.kts

​build.gradle

​Install with Maven

​build.gradle.kts

​Usage

​Importing the Library

​Connect

​Get Data Key

Introduction

Connect Flow

Connect Helper Package

Install Using Swift Package Manager in Xcode

Or Update Package.swift

Usage

Import the package

Initialization

Generating URL

Install Using Swift Package Manager in Xcode

Or Update Package.swift

Usage

Import the package

Initialization

Generating URL

Install

Usage

Import the package

Connect

Install with Gradle

build.gradle.kts

build.gradle

Install with Maven

build.gradle.kts

Usage

Importing the Library

Connect

Get Data Key

Introduction

Connect Flow

Connect Helper Package

Install Using Swift Package Manager in Xcode

Or Update Package.swift

Usage

Import the package

Initialization

Generating URL

Install Using Swift Package Manager in Xcode

Or Update Package.swift

Usage

Import the package

Initialization

Generating URL

Install

Usage

Import the package

Connect

Install with Gradle

build.gradle.kts

build.gradle

Install with Maven

build.gradle.kts

Usage

Importing the Library

Connect

Get Data Key