Social API

To Share and +4 nLEARNs

import Tabs from ‘@theme/Tabs’;
import TabItem from ‘@theme/TabItem’;

VM provides a convenient API to get data from the SocialDB contract. There are four methods:

Social.get

Social.get fetches the data from the SocialDB contract by calling get and returns the data.
While the data is fetching the returned value equals to null.

::note
If the path pattern is a single key, it will try to unwrap the object until the first wildcard.

::

The method takes up to 3 arguments:

param required type description
patterns required string / string[] the path pattern(s)
finality optional "final" / number the block height or finality
options optional object the options object.

:::info options object

  • subscribe (optional): if true, the data will be refreshed every 5 seconds.
  • return_deleted (optional): whether to return deleted values (as null). Default is false.

:::

The block height or finality can be used to get the data at a specific block height or finality.
If the block height or finality is not specified, the data will be fetched at the optimistic finality (the latest block height).

For block height and finality final, instead of calling the NEAR RPC directly, the VM uses the Social API Server to fetch the data.
Social API server indexes the data for SocialDB and allows to fetch the data at any block height with additional options.
It also allows returning more data than an RPC call because it’s not restricted by the gas limit.
In general, the API server also serves data faster than the NEAR RPC, because it doesn’t execute the contract code in a virtual machine.

Social.get options are similar to the SocialDB’s get API.

Examples

For example, if the path pattern is mob.near/widget/*, the Social.get will unwrap the object and return the following:


“`js
const data = Social.get(“mob.near/widget/*”);
“`


“`json
{
“HelloWorld”: “return

Hello, World!

;”,
“HelloUsername”: “return

Hello, {props.username}!

;”
}
“`


If the path pattern is mob.near/widget/HelloWorld, the Social.get will unwrap the object and return the actual value:


“`js
const data = Social.get(“mob.near/widget/HelloWorld”);
“`


“`json
“return

Hello, World!

;”
“`


It’s helpful that you don’t have to manually unwrap object.


Social.getr

Social.getr is just a wrapper helper for Social.get, it appends ** to each of the path pattern.

param required type description
patterns required string / string[] the path pattern(s)
finality optional "final" / number the block height or finality
options optional object the options object.

:::info options object

  • subscribe (optional): if true, the data will be refreshed every 5 seconds.
  • return_deleted (optional): whether to return deleted values (as null). Default is false.

:::

Examples

For example, if the path pattern is mob.near/profile, Social.getr will call Social.get with the path pattern mob.near/profile/**.


“`js
const data = Social.getr(“mob.near/profile”);
“`


“`json
“return

Hello, World!

;”
“`



Social.keys

It calls the SocialDB’s keys API and returns the data. While the data is fetching the returned value equals to null.
The keys contract doesn’t unwrap the object, so the returned data is the same as the SocialDB’s keys API.

Social.keys takes up to 3 arguments:

param required type description
patterns required string / string[] the path pattern(s)
finality optional "final" / number the block height or finality
options optional object the options object.

:::info options object

  • subscribe (optional): if true, the data will be refreshed every 5 seconds.
  • return_type (optional): either "History", "True", or "BlockHeight". If not specified, it will return the "True".
  • return_deleted (optional): whether to return deleted values (as null). Default is false.
  • values_only (optional): whether to return only values (don’t include objects). Default is false.
:::

::tip
The Social API server supports custom options return_type: "History". For each matching key, it will return an array containing all the block heights when the value was changed in ascending order.
It can be used for building a feed, where the values are overwritten.

::

Examples


“`js
const data = Social.keys(`${accountId}/post/meme`, “final”, {
return_type: “History”,
});
“`


“`json
“return

Hello, World!

;”
“`



Social.index

Returns the array of matched indexed values. Ordered by blockHeight.

Social.index arguments:

param required type description
action required string is the index_type from the standard, e.g. in the path index/like the action is like.
key required string is the inner indexed value from the standard.
options optional object the options object.

:::info options object

  • subscribe (optional): if true, the data will be refreshed every 5 seconds.
  • accountId (optional): If given, it should either be a string or an array of account IDs to filter values by them. Otherwise, not filters by account Id.
  • order (optional): Either asc or desc. Defaults to asc.
  • limit (optional): Defaults to 100. The number of values to return. Index may return more than index values, if the last elements have the same block height.
  • from (optional): Defaults to 0 or Max depending on order.

:::

Examples


“`jsx
return Social.index(“test”, “test-key-2”);
“`

“`jsx
return Social.index(“test”, “test-key-2”, {
accountId: “mob.near”
});
“`

“`jsx
return Social.index(“test”, “test-key-2”, {
accountId: [“mob.near”, “root.near”]
});
“`


“`json
[
{
“accountId”: “mob.near”,
“blockHeight”: 78672789,
“value”: “test-value-1”
},
{
“accountId”: “mob.near”,
“blockHeight”: 78672797,
“value”: “test-value-1”
},
{
“accountId”: “mob.near”,
“blockHeight”: 78672974,
“value”: “test-value-3”
}
]
“`


Social.set

Takes a data object and commits it to SocialDB. It works similarly to
the CommitButton by spawning the modal window prompt to save data, but
it doesn’t have to be triggered through the commit button component. It
allows you to write more flexible code that relies on async promises and
use other events and components. Overall it enables more flexibility
when committing to SocialDB. For example, you can commit when Enter key
pressed.

Social.set arguments:

param required type description
data required object the data object to be committed. Similar to CommitButton, it shouldn’t start with an account ID.
options optional object optional object.

:::info options object

  • force (optional): whether to overwrite the data.
  • onCommit (optional): function to trigger on successful commit. Will pass the
    data that was written (including accountID).
  • onCancel (optional): function to trigger if the user cancels the commit.

:::

Ability to skip confirmation

When a modal window to confirm a commit is shown, it has a toggle to
select whether you want to confirm the action every time, or don’t show
the confirm window for similar data.

By default for new data the toggle is set to on, which means the user will not be prompted to
confirm the data for the next time. It remembers the decision locally
and will be default to this decision next time (in case the user decides
to not skip). If the user approves the commit with the toggle on, then the
next commit with similar data will skip the confirmation window. The
permission is given per widget source.

::note

Similar data means the same top level keys on the data. Except for the
4 top level keys: graph, post, index and settings. For these
keys, the second level key will be used. More keys can be added later,
once new standards added.

::

For example the follow button widget uses the following keys:

{
    "graph": {
      "follow": ...
    },
    "index": {
      "graph": ...
      "notify": ...
    }
  }

If it attempts to modify something else, the confirmation modal will be
shown again.

saving data

Examples

Example on using CommitButton and Social.set with a regular button.
Note, both use force


“`jsx
State.init({ commitLoading: false });

const data = { experimental: { test: “test” } };

const Loading = (

);

return (


CommitButton

);
“`


Generate comment with AI 2 nL
Scroll to Top
Report a bug👀