Skip to main content

Usage

In this section, we showcase the aspects of using the Notify API. We'll guide you through the initial steps of initializing the Notify client and logging in a blockchain account. You'll also learn how to manage your subscriptions and messages. Additionally, we cover the process of setting up and displaying push notifications on your preferred platform. To ensure a good user experience, we include best practices for spam protection, helping you to enable the users to maintain control over the notifications wallet receives.

Content​

Links to sections on this page. Some sections are platform specific and are only visible when the platform is selected. To view a summary of useful platform specific topics, check out Extra (Platform Specific) under this section.

Initialization​

Don't have a project ID?

Head over to WalletConnect Cloud and create a new project now!

Get startedcloud illustration

Important: Confirm you have configured the Network Client first.

Configure the Notify instance with:

try Notify.configure(environment: APNSEnvironment, crypto: CryptoProvider)

environment - Use debug environment for debug builds and release for release and TestFlight builds.

crypto - CryptoProvider is a protocol, you are required to provide an implementation of recoverPubKey and keccak256 methods.

Account login​

In order to register account in Notify API to be able to subscribe to any dapp to start receiving notifications, account needs to sign SIWE message to prove ownership. Developers can check if an account is registered by calling isRegistered() function. If the account is not registered, developers should call prepareRegistration() and then register() function to register the account.

To login to manage notifications, you must request message to sign with prepareRegistration() method and register signature with register() method. Once logged in, cross-device syncing will be enabled.

let params = try await Notify.instance.prepareRegistration(account: account, domain: "com.YOURAPPDOMAIN")
let signature = onSign(message: params.message) // Sign message with your signer
try await Notify.instance.register(params: params, signature: signature)
  • account - An CAIP-10 account that the identity key will be issued for
  • domain - A domain of your wallet, you should use your bundle ID

Provide your own sign function implementation that returns CacaoSignature. If SIWE is not implemented on your app you can always use our MessageSignerFactory and DefaultSignerFactory from our sample app that uses Web3 SPM package.

func onSign(message: String) -> CacaoSignature {
    let privateKey = Data(hex: privateKey)
    let signer = MessageSignerFactory(signerFactory: DefaultSignerFactory()).create()
    let signature = try! signer.sign(message: message, privateKey: privateKey, type: .eip191)
    return signature
}

Subscribing to a new dapp​

To begin receiving notifications from a dapp, users must opt-in by subscribing. This subscription process grants permission for the dapp to send notifications to the user. These notifications can serve a variety of purposes, such as providing updates on the user's blockchain account activities or informing them about ongoing campaigns within the dapp. Upon initial subscription, clients will be automatically enrolled to receive all types of notifications as defined by the dapp at that moment. Users have the flexibility to modify their notification settings later, allowing them to tailor the types of alerts they receive according to their preferences.

public func subscribe(appDomain: String, account: Account) async throws

appDomain - dapp domain fetched from WalletConnect explorer

account - an account you want to associate a sebscription with

Combine event​

public var subscriptionsPublisher: AnyPublisher<[NotifySubscription], Never>

Fetching active subscriptions​

To fetch the current list of subscriptions an account has, call getActiveSubscriptions().

Method will return an array of NotifySubscription objects that indicates actual subscriptions state

public func getActiveSubscriptions(account: Account) -> [NotifySubscription]

account - subscriptions owner account

Fetching subscription’s notifications​

To fetch subscription’s notifications by calling getNotificationHistory().

Method will return an array of NotifyMessageRecord objects that indicates current notify messages state. This do not include old messages that aren't loaded yet. Useful for displaying initial notifications view state. For more info about pagination, check fetchHistory method.

Use this method together with:

  • messagesPublisher(topic: String)
  • fetchHistory
public func getMessageHistory(topic: String) -> [NotifyMessageRecord]

topic - unique subscription's topic

Combine events​

Publisher that send messages update event for specific topic only

public func messagesPublisher(topic: String) -> AnyPublisher<[NotifyMessageRecord], Never>

Publisher that send event on every messages update (for all subscriptions)

public var messagesPublisher: AnyPublisher<[NotifyMessageRecord], Never>

Updating subscriptions notification settings​

Users can alter their notification settings to filter out unwanted alerts from a dapp. During this process, they review and select the types of notifications they wish to receive, based on the latest options provided by the dapp.

public func update(topic: String, scope: Set<String>) async throws

topic - topic of the subscription to update

scope - The new space delimited list of scopes

Unsubscribe from a dapp​

To opt-out of receiving notifications from a dap, a user can decide to unsubscribe from dapp.

try await Notify.instance.deleteSubscription(topic: String)

topic - subscription's topic

Account logout​

If an account is removed from the client or a user no longer wants to receive notifications for this account, you can logout the account from Notify API by calling unregister(). This will remove all subscriptions and messages for this account from the client’s storage.

public func unregister(account: Account) async throws

account - account ot unregister

Fetch notification history (Pagination)​

Method that fetches notification history and saves it to SDK's database. When async method finishes execution, messagesPublisher(topic: String) will send the event with actual Notify messages for the specified topic.

func fetchHistory(subscription: NotifySubscription, after: String?, limit: Int) async throws -> Bool

subscription - subscription for which notification history is requested after? - id of last notification loaded. Recent notifications will be loaded if provided nil limit - notifications to load count

Returns - Returns True if there are still not fetched notifications

Apple Push Notification service setup​

To setup Apple Push Notification service please follow our Push Notifications docs.