BitBadges
  • Overview
    • ๐Ÿ‘‹BitBadges Overview
    • ๐Ÿ‘จโ€๐Ÿ’ปLearn the Basics
      • BitBadges Claims
      • Multi-Chain Accounts
      • Sign In with BitBadges
      • Badges
      • Address Lists
      • Attestations
      • Applications (Points)
      • Additional Badge Concepts
        • Manager
        • Total Supplys
        • Time-Dependent Ownership
        • Transferability
        • Balances Types
      • Wallets and Sign Ins
        • Supported Wallets
        • Alternate Sign Ins / Mobile
        • Approved Transactors
    • ๐Ÿ”จGetting Started
    • ๐Ÿ’ปHow Do I Check...?
    • ๐Ÿ”How Do I Gate...?
    • ๐ŸŽจUse Cases
    • ๐Ÿ”—Official Links and Resources
    • โš–๏ธBitBadges L1 vs Others
    • ๐Ÿช™Launch Phases
    • ๐ŸŒดEcosystem
      • WordPress Plugin
      • MetaMask Snap
      • Browser Extensions
      • LinkedIn Certifications
      • Blockin
    • ๐ŸคBrand Guidelines
    • โ“FAQ
  • โŒจ๏ธFor Developers
    • ๐Ÿšดโ€โ™‚๏ธGetting Started
    • ๐Ÿ‘คHandling Addresses
    • ๐ŸงชTestnet Mode
    • ๐Ÿ“šBitBadges API
      • Getting Started
      • Full Reference
      • Typed SDK Types
      • Upgrading an API Key Tier
      • Concepts
        • Native Chain Algorithm
        • Refresh / Claim Completion Queue
        • Designing for Compatibility
        • Limits / Restrictions
        • Managing Views
        • Use via Pipedream
    • ๐Ÿ–ฑ๏ธSign In with BitBadges
      • Overview
      • Already Have Web3 Auth?
      • Alternative - P2P Verification
      • Templates and Frameworks
        • WordPress
        • Auth0
        • ExpressJS
        • Discourse
        • Supabase
        • Others
      • Setting Up an App
      • Connecting a Claim
      • Authorization URL
        • Configuration
        • Generating the URL
      • Approaches
        • QR Codes
        • Redirect Callback
      • Verification
        • Verification Flow
        • Access Tokens
        • Offline Verification
        • Security Considerations
      • Blockin Docs
    • ๐Ÿ—๏ธBitBadges Claims
      • Overview
      • Concepts
        • Standard vs On-Demand
        • Completion Methods
        • Gating Badge Distribution
        • Claim Numbers
        • Success Logic
        • Claim Links (URLs)
        • Signed In vs Select Address
        • Universal Approach - Claim Codes
        • Identify By Socials / Emails?
        • Payment Checking
        • Receiving Attestations
      • Checking Custom Criteria
      • Implementing Custom Utility
      • Leveraging AI
      • BitBadges API & Claims
        • Verifying Claim Attempts w/ the API
        • Fetching Claims
        • Auto-Complete Claims w/ BitBadges API
      • Dynamic Stores
        • Overview
        • Adding Data
      • Custom Plugins / Webhooks
        • Overview
        • Pre-Built Webhook Plugins
        • Creating a Custom Plugin
          • Implement Your Plugin
            • Getting Started
            • Hook Types and Simulations
            • Design Considerations
            • Parameters
            • Custom Inputs
            • API Handler
          • Managing Your Plugin
          • Testing Your Plugin
        • Configuration Tools
      • Integrate with Zapier
        • Overview
        • Dynamic Store Zaps
        • Automatic Claim Tutorial
        • Post-Success Zaps
        • Leveraging Zapier AI Actions / MCP
        • Automate Any Part of the Process
          • Google Forms
      • Integrate with Pipedream
        • Overview
        • Leveraging Pipedream MCP
        • Build Custom Plugins
        • Workflow Actions
          • Complete Claim
          • Get Claim Attempt Status
          • Get Claim Code by Idx
          • Add User to Dynamic Store
        • Workflow Triggers
          • Poll Claim Attempts
        • End to End Example
      • In-Site Plugins
        • Plugins Directory
        • Plugin Documentation
        • Ownership Requirements
      • Tutorials
        • In-Site Guides
        • Get Integration User IDs
          • Get Discord User ID
          • Get Discord Server ID
          • X / Twitch / GitHub IDs
        • Add Telegram Bot to Channel
    • โš’๏ธBitBadges JS / SDK
      • Overview
      • SDK Types
      • Common Snippets
        • Address Conversions
        • NumberType Conversions
        • Uint Ranges
        • Balances
        • Transfers
        • Address Lists
        • Badge Metadata
        • Approvals / Transferability
        • Off-Chain Balances
        • Timelines
    • ๐ŸŒŸBadges - Advanced
      • Overview
      • Balances / Transfers
        • ๐Ÿ“ŠBalances
        • โž•Valid Badge IDs
        • ๐Ÿช™Balance Types
        • ๐ŸคTransferability / Approvals
        • โœ…Approval Criteria
          • Overview
          • $BADGE Transfers
          • Override User Level Approvals
          • Approval Trackers
          • Tallied Approval Amounts
          • Max Number of Transfers
          • Predetermined Balances
          • Requires
          • Merkle Challenges
          • Extending the Approval (Advanced)
      • Self-Hosted Balances
        • Overview
        • Examples / Tutorials
          • Indexed
          • Non-Indexed
      • Permissions
        • Overview
        • Action Permission
        • Timed Update Permission
        • Timed Update With Badge Ids Permission
        • Badge IDs Action Permission
        • Update Approval Permission
      • Standards
      • Archived Collections
      • Metadata
      • Timelines
      • Different Time Fields
      • List IDs
      • Uint Ranges
    • โ›“๏ธBitBadges Blockchain
      • Overview
      • Chain Details
      • REST API Docs - Node
      • Staking / Validators
      • Run a Node
        • Overview
        • Run a Mainnet Node
        • Run a Local Dev Node
        • Cosmovisor
      • Create a Smart Contract
      • ๐Ÿ”ƒCreate, Generate, and Sign Txs
        • Transaction Context
        • Generate Msg Contents
        • Signing - Cosmos
        • Signing - Ethereum
        • Signing - Solana
        • Signing - Bitcoin
        • Broadcast to a Node
        • Sign + Broadcast - bitbadges.io
      • ๐Ÿ“ฉCosmos SDK Msgs
        • x/anchor
          • MsgAddCustomData
        • x/badges
          • MsgCreateCollection
          • MsgUpdateCollection
          • MsgDeleteCollection
          • MsgCreateAddressLists
          • MsgTransferBadges
          • MsgUpdateUserApprovals
          • MsgUniversalUpdateCollection
        • x/wasmx
          • MsgStoreCodeCompat
          • MsgInstantiateContractCompat
          • MsgExecuteContractCompat
        • x/maps
          • MsgCreateMap
          • MsgUpdateMap
          • MsgDeleteMap
          • MsgSetValue
        • MsgSend
        • Cosmos Native Msgs
    • ๐Ÿง Other Concepts
      • Uint Ranges
      • Accounts (Low-Level)
      • Address Lists
      • Maps / Protocols
      • Attestations - Advanced
        • Overview
        • Creating an Attestation
        • Custom Creation Links
        • Proofs vs Attestations
        • Deriving a Proof
        • Design Considerations
        • Verification / Presentations
        • Custom Schemes
          • WITNESS Proofs
Powered by GitBook
On this page
  • How Bookmark Pagination Works
  • Understanding the Views Object
  • Key Components
  • Document ID Mapping
  • Common View Types
  • Helper Functions
  • Best Practices
  1. For Developers
  2. BitBadges API
  3. Concepts

Managing Views

Throughout the BitBadges API, we use a bookmark-based pagination system for efficient data retrieval. This system is particularly useful when dealing with large datasets that need to be fetched in smaller chunks.

Some endpoints like the get accounts or get collections will use a generic viewsToFetch and views object which can maintain multiple paginated views. Some endpoints will request the bookmark directly. Refer to the documentation for each endpoint to see how it handles pagination.

How Bookmark Pagination Works

  1. First Request: For your initial request, use an empty bookmark string ("").

const firstRequest = {
    viewType: 'owners',
    viewId: 'owners',
    bookmark: '', // Empty for first page
};
  1. Response Structure: Each paginated response includes:

    • The requested data

    • A bookmark string for the next page

    • A hasMore boolean indicating if more data exists

{
    data: [...],
    views: {
        'owners': {
            ids: [...],
            pagination: {
                bookmark: 'abc123...', // Use this for next request
                hasMore: true
            }
        }
    }
}
  1. Subsequent Requests: To fetch the next page, use the bookmark from the previous response:

const nextRequest = {
    viewType: 'owners',
    viewId: 'owners',
    bookmark: 'abc123...', // Bookmark from previous response
};
  1. Completion: Continue this process until hasMore is false.

Understanding the Views Object

Note: This is planning to be deprecated in favor of more confined view routes. 
Please use those instead. They are much less confusing.

The views object is a central concept in the BitBadges API, used to manage paginated data across different interfaces (BitBadgesCollection, BitBadgesAddressList, BitBadgesUserInfo, etc). It follows this structure:

views: {
    [viewId: string]: {
        ids: string[];          // Array of document IDs
        pagination: {
            bookmark: string;    // Bookmark for next page
            hasMore: boolean;    // Whether more data exists
        };
        type: string;           // The view type
    } | undefined;
}

Key Components

  1. viewId: A unique identifier for the view

  2. ids: Array of document IDs that correspond to full documents in the response

  3. pagination: Contains the bookmark and hasMore flag

  4. type: Indicates the type of view (e.g., 'owners', 'activity', etc.)

Document ID Mapping

Documents in the response are referenced by their _docId field. To access the full document, you map the IDs from the view to the corresponding array in the response. For example, the activity view documents are stored in the activity array, and the view IDs are stored in the views.activity.ids array.

// Example of accessing activity documents from a view
getActivityView(viewId: string) {
    return (this.views[viewId]?.ids.map((x) => {
        return this.activity.find((y) => y._docId === x);
    }) ?? []);
}

Common View Types

Different interfaces support different view types. See the corresponding documentation for each interface to see what views are supported.

Collections Interface

  • owners: List of badge owners

  • activity: Transfer activity

  • approvalTrackers: Approval tracking documents

Account Interface

  • transferActivity: User's transfer history

  • badgesCollected: Badges owned by the user

  • createdBadges: Collections created by the user

  • managingBadges: Collections being managed

  • allLists: Address lists the user is on

Helper Functions

The BitBadges SDK provides several helper functions for managing views:

// Check if more pages exist
const hasMore = collection.viewHasMore('owners');

// Get bookmark for next page
const nextBookmark = collection.getViewBookmark('owners');

// Fetch next page of data
await collection.fetchNextForView(BitBadgesApi, 'owners', 'owners');

// Get all documents for a view
const ownersView = collection.getOwnersView('owners');

Best Practices

  1. Consistent ViewIds: Use consistent viewIds when paginating through the same dataset

  2. Error Handling: Always check for undefined views before accessing

  3. Document Mapping: Use helper functions when available for mapping IDs to documents

  4. Pagination State: Track both bookmark and hasMore status for proper pagination

  5. Response Merging: Remember that each response is confined to its request - use helper functions or manually merge data as needed

PreviousLimits / RestrictionsNextUse via Pipedream

Last updated 2 months ago

See all at

See all at

โŒจ๏ธ
๐Ÿ“š
CollectionViewKey
AccountViewKey