Cross-app shares

Apps can offer a fixed, read-only slice of their content to other apps. Each slice is a share, named share:<provider>.<feature>: share:blog.posts is the blog app’s list of published posts. Your app lists the shares it wants in cskn.json, asks the user, and reads them with the SDK.

import { useCrossApp } from '@cskn/sdk';

function LatestPosts({ username }: { username: string }) {
  const posts = useCrossApp('blog', 'posts', { username, limit: 3 });
  if (posts.items.length === 0) return null;

  return (
    <ul>
      {posts.items.map(post => (
        <li key={post.id}><a href={post.url ?? undefined}>{post.title}</a></li>
      ))}
    </ul>
  );
}

Whose permission counts

Every share has a subject: whose content it returns. The subject decides who has to say yes.

Subject	Returns	Who grants it
`self`	The viewer’s own content	The viewer, through your app
`user`	One person’s content, named by `username`	That person. The viewer needs nothing, and doesn’t have to be signed in.
`grantors`	Content from everyone who granted the share to your app	Each of those people. The viewer needs nothing.

The platform applies the owner’s visibility before anything comes back. If someone shows an app to followers only, a visitor who doesn’t follow them gets nothing. Blocked people and suspended accounts are left out too. What a share returns is safe to show as it is.

Declaring what you want

List the shares in the crossApp field of your app’s cskn.json. Each deploy publishes the list:

{
  "crossApp": ["share:blog.posts", "share:photos.recent"]
}

A share that isn’t listed can’t be asked for or read, even if a user granted it to your app before. Listing one is only a request. The user’s grant is what lets you read it. The deploy warns you about a share its provider doesn’t offer, or one that is limited to some apps. It still publishes the list, because the provider may add the share later.

cskn.json is the only source. If you remove a share from crossApp, the next deploy stops your app from reading it.

Reading

useCrossApp(provider, feature, options) reads a share page by page. It is a TanStack Query useInfiniteQuery.

string

required

The app that offers the share, for example blog.

string

required

The share’s name within that app, for example posts.

string

Whose content to read. Required for a user share.

number

Page size. The platform clamps it: 20 by default, at most 50, and a share can set lower bounds.

boolean

default:"true"

Set to false to hold the request.

T[]

Every page loaded so far, flattened. Typed per share; see Typing a share.

CrossAppError | null

The platform’s reason for refusing, or null. A refusal is not retried.

function / boolean

From useInfiniteQuery. Load more while hasNextPage is true.

A refusal is the normal case on most profiles: the owner hasn’t shared, or shows the app to some people only. If you show a share on someone’s user page, draw nothing when it is refused rather than an error. Without React, use readCrossApp(provider, feature, { username, limit, cursor }). It resolves to { items, nextCursor }. Pass nextCursor back as cursor for the next page. It is null on the last page.

Signed-out visitors

A user share can be read with no session, so a visitor to a user page sees the owner’s content. The SDK names your app on the request. The platform then returns only what the owner shows to everyone. A self or grantors share needs a signed-in user. useCrossAppAccess(scopes) returns what the user said to each share and a request function that opens the consent screen.

import { useCrossAppAccess, crossAppText } from '@cskn/sdk';

function ShowMyPosts() {
  const access = useCrossAppAccess('share:blog.posts');
  const share = access.shares[0];

  return (
    <label>
      <input
        type="checkbox"
        checked={access.granted}
        disabled={!share || access.requesting}
        onChange={e => (e.target.checked ? access.request() : access.revoke())}
      />
      Show {share ? crossAppText(share.description) : 'my posts'} here
    </label>
  );
}

string | string[]

The shares this screen is about. Leave it out to cover every share in your cskn.json.

boolean

true when every share in scope is granted. false while loading.

CrossAppAccessShare[]

One entry per share: scope, subject, description ({ en, tr }), granted, providerName, and providerActivated (whether the user has the provider app turned on).

string[]

The shares in scope the user hasn’t granted.

(only?: string[]) => Promise<CrossAppRequestResult>

Opens the consent screen for the missing shares, or for only. Call it from a tap or a click.

(only?: string[]) => Promise<{ changed: boolean }>

Gives back the granted shares in scope, or only.

request never rejects. It resolves to { granted, declined, error? }:

granted lists the shares that are granted now, including ones granted before.
declined lists the rest.
error is set only when the user wasn’t asked.

The user saying no is not an error. Shares granted before aren’t asked again. After the screen closes, every cross-app query refreshes. Ask for what the screen in front of the user needs, not for everything in your cskn.json. For a self share, asking is how you get to read it. For user and grantors shares, asking is how the viewer shares their own content with your app.

Where your app runs	What happens
Mobile, desktop	The shell shows its own consent sheet. It answers after the grant is saved and your app holds a token that carries it, so your next read already works.
Browser, app page	A popup with the cskn consent screen. If the browser blocks it, the page goes there and comes back to the same URL. `redirected` is then `true`. Read the access again after the reload.
User page, TV, older app versions	No consent screen: `error: 'not_available'`. Grants are stored on the account, so a grant given on a phone holds on the TV too.

Without React, use requestCrossApp(scopes) and getCrossAppAccess().

`error`	Meaning
`not_available`	This surface can’t ask. See the table above.
`no_gesture`	Called without a tap or click, or while your app wasn’t on screen.
`busy`	A consent screen is already open.
`not_activated`	The user has turned your app off.
`invalid`	A scope isn’t of the form `share:<provider>.<feature>`.
`popup_closed`	Browser only: the user closed the popup.
`failed` / `timeout`	The grant couldn’t be read or saved. Try again later.

revokeCrossApp(scopes), or revoke from the hook, stops your app from holding a share for the signed-in user. Use it for an in-app “stop showing this” switch. It can only narrow your app’s access. Granting always goes through the consent screen. Users can also take shares back themselves. On mobile and desktop they do it under Profile → App access. Your app sees that as granted: false the next time it reads the access.

Shares you can use

One person’s published posts, newest first. Drafts never appear. Default page 5, at most 20.

Field	Type
`id`	`string`
`title`	`string`
`excerpt`	`string`	Empty when the post has none.
`coverImage`	`string \| null`
`category`	`string`
`readTime`	`number`	Minutes.
`createdAt`	`string`	ISO time.
`url`	`string \| null`	The post on its owner’s blog.

One person’s latest public photos. A private photo never appears, not even to its owner. Default page 12, at most 30.

Field	Type
`id`	`string`
`caption`	`string`	Empty when the photo has none.
`thumbnail`	`string`	Square, grid quality.
`image`	`string`	Native aspect ratio.
`width` / `height`	`number`	Original dimensions.
`createdAt`	`string`	ISO time.
`url`	`string \| null`	The photo on its owner’s page.

Image URLs are signed and expire. Show them, but never store them.

getCrossAppCatalog(provider) lists what a provider offers: each share’s feature, subject and description, and restricted when only some apps may ask for it. readCrossApp and useCrossApp type items from the CrossShareMap interface. The shares above are already in it as CrossBlogPost and CrossPhoto. For any other share, add its type yourself:

declare module '@cskn/sdk' {
  interface CrossShareMap {
    'recipes.latest': { id: string; title: string; url: string | null };
  }
}

A share that isn’t in the map reads as unknown.

Refusals

crossAppError(error) returns { code, status, message } for a refused read, or null for anything else, such as a network failure.

`code`	Meaning
`SCOPE_NOT_GRANTED`	A `self` share the viewer hasn’t granted. Ask with `request`.
`SHARE_NOT_GRANTED_BY_OWNER`	That person hasn’t shared this with your app.
`NOT_VISIBLE`	They show the provider app to some people only, and the viewer isn’t one of them.
`USER_NOT_FOUND`	No such person, or a block between them and the viewer.
`SHARE_NOT_DECLARED`	Your `cskn.json` doesn’t list this share.
`CONSUMER_NOT_ALLOWED`	The provider only lets some apps ask for this share.
`SHARE_NOT_FOUND`	No such share.
`USERNAME_REQUIRED`	A `user` share was read without `username`.
`APP_TOKEN_REQUIRED`	A `self` or `grantors` share was read signed out.

Overview

Platform API

Native features

Profile integration

Reference

Whose permission counts

Declaring what you want

Reading

Signed-out visitors

Shares you can use

Refusals

​Whose permission counts

​Declaring what you want

​Reading

​Signed-out visitors

​Asking for a share

​Where the consent screen appears

​Giving a share back

​Shares you can use

​Typing a share

​Refusals

Whose permission counts

Declaring what you want

Reading

Signed-out visitors

Asking for a share

Where the consent screen appears

Giving a share back

Shares you can use

Typing a share

Refusals