Skip to main content

Enrich with AppsDB

||

Now that your Showpad App is nearing completion, you can enrich it by using the AppsDB. This is essential for providing your app with offline capabilities.

To do so, you need to update your main.ts file. In essence, you need to add the code for:

  1. Store
  2. User-Scoped Entries
  3. Globally-Scoped Entries

The following sections provide a description of each operation that can be performed, as well as a link to the function to use.

tip

You can preview a completed end result, take a look at our working example.

Store​

A store is the top-level object which groups multiple store entries together. In other words, it's where your Showpad data is stored. It can hold both user-scoped and globally-scoped entries (at the same time).

Your store must be registered before it can be used. This is done by defining the store in the manifest or by using the createStore() SDK function.

caution

If the store already exists, an error will be thrown.

User-Scoped Entries​

User-scoped entries are intended for data that's unique to a particular user and only available to them. For example, if a user is having a conversation with a client and data needs to be stored, this data can only be retrieved by this particular user.

AppsDB allows you to perform the following CRUD operations for user-scoped entries.

Create or Update​

You can create a new user-scoped entry or update an existing user-scoped entry with the setStoreEntryValue() function.

Read​

To retrieve the value of a user-scoped entry, the getStoreEntryValue() function must be used.

To retrieve all user-scoped entries, the getStoreEntries() function must be used.

Delete​

To permanently remove a single user-scoped entry, use the deleteStoreEntry() function.

Warning

This action is irreversible. Once an entry has been deleted, it can't be recovered.

Globally-Scoped Entries​

Globally-scoped entries are any information that can be accessed and retrieved by all users. For example, marketing or sales materials for products.

AppsDB allows you to perform the following CRUD operations for globally-scoped entries.

Create or Update​

You can create a new globally-scoped entry or update an existing globally-scoped entry with the setGlobalStoreEntryValue() function.

Read​

To retrieve a globally-scoped entry, the getGlobalStoreEntryValue() function must be used.

To retrieve all globally-scoped entries, the getGlobalStoreEntries() function must be used.

Delete​

To permanently remove a globally-scoped entry, use the deleteGlobalStoreEntry() function.

Warning

This action is irreversible. Once an entry has been deleted, it can't be recovered.

Working Example​

If you want to jump right in, we've prepared an extensive example that you can copy and replace the contents of the main.ts file.

This example code will only work if executed by an administrator or owner user because following functions require create, update or delete permissions on globally scoped entries:

Administrator or owner users have those permissions. For non-administrator users, you need to use an OAuth client as explained in: Updates for non-admins.

This code will create a Showpad App with buttons to make the calls to AppsDB. The example includes inline comments to explain each step.

Updates for Non-Admins​

You can grant AppsDB global create, update, and delete permissions to non-administrator users. For this, you will need a configured OAuth client. The non-administrator users will then need to enter their password (once) to execute AppsDB functions that require those permissions.

Don't hard code secrets

You should never store the clientSecret hard coded in your Showpad App. It's better to store it in the configuration as explained in the following example.

Initially, you'll add labels and assets to your config.json file:

{
  "version": 1,
  "labels": {
    "settings": {
      "clientId": "CLIENT_ID",
      "clientSecret": "CLIENT_SECRET",
      "allowedEmails": "LIST OF ALLOWED EMAILS SEPARATED BY COMMA"
    },
    "views": {},
    "components": {}
  },
  "contents": {}
}

Known Limitations​

The AppsDB offers flexible and lightweight data storage for apps, but there are several limitations to keep in mind, especially when planning for large-scale or multi-user usage.

Description
DB size limitThere is currently no enforced limit on the overall size of the database.
Maximum entriesThere is no set limit on the total number of entries that can be stored.
Maximum data per entryEach entry is limited to 250,000 bytes when using the database directly.

If the SDK is used, entries can be up to 10MB, as the SDK chunks the data into 250,000-byte segments.
Synchronization speedSeveral factors influence sync speed, and we do not guarantee real-time synchronization:

  • If two users are using the Web App, and one is modifying data while the other is actively reading it, the changes should be visible within a few seconds (in the worst case).

  • If one user is on the mobile app or the Windows Desktop App, synchronization depends on how data is retrieved (via SDK or not). In the worst case, syncing may take up to 6 minutes (assuming the mobile user is online).
In general, we recommend using the SDK for interacting with the AppsDB to ensure the most reliable synchronization.
Conflict handlingAppsDB is not built for concurrent multi-user read/write access to the same entries. Issues may include:

  • When multiple users write to the same entry at nearly the same time, the final state is unpredictable (last write wins).

  • If one user edits an entry offline while another edits it online, the offline user's version may overwrite the online version when they reconnect.
Performance considerationsAppsDB is optimized for smaller data objects (e.g., metadata). Storing large entries may lead to degraded performance.

Was this page helpful?