Backup methods

A guide that goes over all of the various backup methods your users can use.

Passkey + Enclave Backup

Allow customers to create a native passkey on their device that is used to authenticate into a secure enclave that holds the encryption key for the user. Customer's passkeys are backed up to the native cloud storage for their device.

Implementation Requirements

Initialize passkey storage as a backup option in the Portal Config Object.
Configuring the relying party

Use Portal as your relying party

Add portalhq.io as a web credential domain in your app.
Share your app bundle id with the Portal Team.

Use your own domain as the relying party

Ensure you have set up your associate domain correctly in your app and that you are serving an aasa file from whatever your relying party domain is set to. You will need to be sure you have the webcredential field set properly for your app in your aasa file.

Resources from apple:

Relying party

A relying party is a trusted domain that is tied to the public key credentials of your users for their passkey . We offer the option to use portalhq.io as your relying party domain. It requires you to add portalhq.io as an Associated Domain in your iOS application and share your team id + application bundle id. If you already have your domain as a webcredential for your application then you can simply pass in your domain as the relying party and everything should work.

import PortalSwift

class ViewController: UIViewController {
  public var portal: Portal?
  public var yourApiUrl: String = "https://YOUR_API_URL.com"
  
  @IBAction func handlePasskeyBackup(_: UIButton!) {
    Task {
      do {
        guard let portal = self.portal else {
          throw PortalExampleAppError.portalNotInitialized()
        }

        // Run passkey backup.
        _ = try await self.backup(.Passkey)
      } catch {
        // Handle any errors during the passkey backup flow.
      }
    }
  }

  public func backup(_ withMethod: BackupMethods) async throws -> String {
    guard let portal else {
      throw PortalExampleAppError.portalNotInitialized()
    }
    guard let config else {
      throw PortalExampleAppError.configurationNotSet()
    }

    // Run backup.
    let (
      encryptedClientBackupShare, 
      storageCallback
    ) = try await portal.backupWallet(withMethod) { status in
      // (Optional) Create a progress indicator here in the progress callback.
    }
  }
}

import PortalSwift

class ViewController: UIViewController {
  public var portal: Portal?
  public var yourApiUrl: String = "https://YOUR_API_URL.com"
  
  @IBAction func handlePasskeyBackup(_: UIButton!) {
    Task {
      do {
        guard let portal = self.portal else {
          throw PortalExampleAppError.portalNotInitialized()
        }

        // Run passkey backup.
        _ = try await self.backup(clientId, withMethod: .Passkey)
      } catch {
        // Handle any errors during the passkey backup flow.
      }
    }
  }

  public func backup(_ userId: String, withMethod: BackupMethods) async throws -> String {
    guard let portal else {
      throw PortalExampleAppError.portalNotInitialized()
    }

    guard let config else {
      throw PortalExampleAppError.configurationNotSet()
    }

    // Run backup.
    let (encryptedClientBackupShare, storageCallback) = try await portal.backupWallet(withMethod) { status in
      // (Optional) Create a progress indicator here in the progress callback.
    }

    // Obtain your API's URL for storing the encrypted user backup share.
    guard let url = URL(string: "\(yourApiUrl)/users/\(userId)/store-encrypted-user-backup-share") else {
      throw URLError(.badURL)
    }

    // Store the encrypted user backup share on your API.
    try await requests.post(
      url,
      andPayload: [
        "backupMethod": withMethod.rawValue,
        "encryptedClientBackupShare": encryptedClientBackupShare,
      ]
    )

    // Call the storageCallback to notify Portal you stored the user backup share successfully.
    try await storageCallback()
    
    // ✅ The user has now backed up with their passkey successfully!
  }
}

Password/Pin Backup

Allow customers to create a password/pin. Customers can either remember the password or store it in a password storage manager.

Implementation Requirements

Create a UI for password input.
Enforce password requirements. Customer can choose between password, PIN code, passcode, or any other text-based input.
If user forgets password there are no additional recovery options.

import PortalSwift

class ViewController: UIViewController {
  public var portal: Portal?
  public var yourApiUrl: String = "https://YOUR_API_URL.com"
  
  @IBAction func handlePasswordBackup(_: UIButton!) {
    Task {
      do {
        guard let portal = self.portal else {
          throw PortalExampleAppError.portalNotInitialized()
        }
        
        // Obtain the user's password.
        guard let enteredPassword = await requestPasswordFromUser() else {
          return
        }
        // Set the user's password.
        try portal.setPassword(enteredPassword)

        // Run backup.
        _ = try await self.backup(.Password)
      } catch {
        // Handle any errors during the password backup flow.
      }
    }
  }

  public func backup(_ withMethod: BackupMethods) async throws -> String {
    guard let portal else {
      throw PortalExampleAppError.portalNotInitialized()
    }
    guard let config else {
      throw PortalExampleAppError.configurationNotSet()
    }

    // Run password backup.
    let (
      encryptedClientBackupShare, 
      storageCallback
    ) = try await portal.backupWallet(withMethod) { status in
      // (Optional) Create a progress indicator here in the progress callback.
    }
}

import PortalSwift

class ViewController: UIViewController {
  public var portal: Portal?
  public var yourApiUrl: String = "https://YOUR_API_URL.com"
  
  @IBAction func handlePasswordBackup(_: UIButton!) {
    Task {
      do {
        guard let portal = self.portal else {
          throw PortalExampleAppError.portalNotInitialized()
        }

        // Obtain the user's password.
        guard let enteredPassword = await requestPasswordFromUser() else {
          return
        }

        // Set the user's password.
        try portal.setPassword(enteredPassword)

        // Run backup.
        _ = try await self.backup(clientId, withMethod: .Password)
      } catch {
        // Handle any errors during the password backup flow.
      }
    }
  }

  public func backup(_ userId: String, withMethod: BackupMethods) async throws -> String {
    guard let portal else {
      throw PortalExampleAppError.portalNotInitialized()
    }

    guard let config else {
      throw PortalExampleAppError.configurationNotSet()
    }

    // Run password backup.
    let (encryptedClientBackupShare, storageCallback) = try await portal.backupWallet(withMethod) { status in
      // (Optional) Create a progress indicator here in the progress callback.
    }

    // Obtain your API's URL for storing the encrypted user backup share.
    guard let url = URL(string: "\(yourApiUrl)/users/\(userId)/store-encrypted-user-backup-share") else {
      throw URLError(.badURL)
    }

    // Store the encrypted user backup share on your API.
    try await requests.post(
      url,
      andPayload: [
        "backupMethod": withMethod.rawValue,
        "encryptedClientBackupShare": encryptedClientBackupShare,
      ]
    )

    // Call the storageCallback to notify Portal you stored the user backup share successfully.
    try await storageCallback()
    
    // ✅ The user has now backed up with their password successfully!
  }
}

iCloud

See the docs on how to Configure iCloud storage.

Google Drive

See the docs on how to Configure GDrive storage.

After initializing Portal, you will need to configure the following:

 func registerPortal() -> Void {
    do {
      // Create a Portal instance.
      portal = try Portal(
        self.clientAuthToken,
        withRpcConfig: [
          "eip155:1": "https://eth-mainnet.g.alchemy.com/v2/\(config.alchemyApiKey)",
          "eip155:11155111": "https://eth-sepolia.g.alchemy.com/v2/\(config.alchemyApiKey)",
          "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "https://api.mainnet-beta.solana.com",
          "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1": "https://api.devnet.solana.com",
        ]
      )
      
      // Set GDrive Configuration
      try portal.setGDriveConfiguration(clientId: config.googleClientId, backupOption: .appDataFolder)
      
      // Set the GDrive presenting view
      try portal.setGDriveView(self)
    } catch {
      // Handle errors creating an instance of Portal.
    }
  }

setGDriveConfiguration function parameters:

clientId: The client ID for the Google Drive integration.
backupOption: An option from the GDriveBackupOption enum that specifies the backup storage type:
- appDataFolder: Stores backups in the hidden, app-specific "App Data Folder" in Google Drive. This folder is not visible to the user.
- appDataFolderWithFallback: Attempts to store backups and recover using the "App Data Folder". If recover fails, it automatically falls back to a user-visible Google Drive.
- gdriveFolder(folderName: String): Stores backups in a user-visible folder in Google Drive with the specified folderName.

setGDriveView function parameters:

view: A UIViewController instance that will be used to present Google Drive UI components.

For the GoogleDrive action handling:

import PortalSwift

class ViewController: UIViewController {
  public var portal: Portal?
  
  @IBAction func handleGdriveBackup(_: UIButton!) {
    Task {
      do {
        guard let portal = self.portal else {
          throw PortalExampleAppError.portalNotInitialized()
        }

        // Run GoogleDrive backup.
        _ = try await self.backup(.GoogleDrive)
      } catch {
        // Handle any errors during the GoogleDrive backup flow.
      }
    }
  }

  public func backup(_ withMethod: BackupMethods) async throws -> String {
    guard let portal else {
      throw PortalExampleAppError.portalNotInitialized()
    }
    guard let config else {
      throw PortalExampleAppError.configurationNotSet()
    }

    // Run backup.
    let (
      encryptedClientBackupShare, 
      storageCallback
    ) = try await portal.backupWallet(withMethod) { status in
      // (Optional) Create a progress indicator here in the progress callback.
    }
  }
}

import PortalSwift

class ViewController: UIViewController {
  public var portal: Portal?
  public var yourApiUrl: String = "https://YOUR_API_URL.com"
  
  @IBAction func handleGdriveBackup(_: UIButton!) {
    Task {
      do {
        guard let portal = self.portal else {
          throw PortalExampleAppError.portalNotInitialized()
        }

        // Run GoogleDrive backup.
        _ = try await self.backup(clientId, withMethod: .GoogleDrive)
      } catch {
        // Handle any errors during the GoogleDrive backup flow.
      }
    }
  }

  public func backup(_ userId: String, withMethod: BackupMethods) async throws -> String {
    guard let portal else {
      throw PortalExampleAppError.portalNotInitialized()
    }

    guard let config else {
      throw PortalExampleAppError.configurationNotSet()
    }

    // Run backup.
    let (encryptedClientBackupShare, storageCallback) = try await portal.backupWallet(withMethod) { status in
      // (Optional) Create a progress indicator here in the progress callback.
    }

    // Obtain your API's URL for storing the encrypted user backup share.
    guard let url = URL(string: "\(yourApiUrl)/users/\(userId)/store-encrypted-user-backup-share") else {
      throw URLError(.badURL)
    }

    // Store the encrypted user backup share on your API.
    try await requests.post(
      url,
      andPayload: [
        "backupMethod": withMethod.rawValue,
        "encryptedClientBackupShare": encryptedClientBackupShare,
      ]
    )

    // Call the storageCallback to notify Portal you stored the user backup share successfully.
    try await storageCallback()
    
    // ✅ The user has now backed up with their passkey successfully!
  }
}

App Data Folder vs. GDrive Files:

App Data Folder: A hidden, app-specific storage area that is not visible to the user in their Google Drive interface. This is ideal for sensitive data or configurations that the user doesn't need to manage directly.
Google Drive Files: A visible folder in the user's Google Drive, accessible and manageable by the user. This is suitable for backups the user might want to view, share, or organize manually.

The App Data Folder feature is supported starting from SDK version 4.2.0. If you enable this feature, ensure that you do not use any SDK version older than 4.2.0, as it will result in the loss of App Data Folder backups.

PreviousBack up a wallet NextRecover a wallet

Last updated 15 days ago