[on hold] Include Mini App state in the shared Mini App URL

[gabrielayuso]

Goal

Let mini apps provide a path and query params to be included in the Mini App URL when the host shares a link to the mini app.

Background

Farcaster clients can generate Mini App URLs such as https://warpcast.com/miniapps/VNo09-kNexFz/farcade to link directly to a mini app. These URLs open the homeURL from the mini app's manifest by default.

The Mini App URLs support passing query params down to the mini app and will soon also be able to pass the path as well.

Example:

https://warpcast.com/miniapps/VNo09-kNexFz/farcade/subpath?foo=bar
          ↓
https://play.farcade.ai/subpath?foo=bar

However, currently mini apps don't have a way to let the host know that they want to add a path and query params to the Mini App URL when sharing.

Proposal

Let mini apps set a function that the host can call to obtain the share state when generating the Mini App URL.

This approach lets the host lazily obtain the share state only when necessary. It also gives mini apps the flexibility to build the path and query params however they like without the need to tie them with navigation state.

Type Definition

type ShareState = {
   /**
    * Query parms to be added to the mini app URL when shared.
    * 
    * Either a key-value pair e.g. `{ foo: 'bar' }`
    * or a string e.g. `'foo=bar'` (can set `window.location.search` directly).
    */
    params: string | Record<string, string>;
   /**
    * The path to be added to the mini app URL when shared. Added either to
    * the `homeUrl` specified in the manifest or the URL of an mini app embed
    * shared on the feed.
    * 
    * e.g. `'/specific/miniapp/screen'` (can set `window.location.pathname` directly).
    */
    path: string;
}

type ShareStateProvider = () => Promise<ShareState>

type FrameSDK = {
 // ...
 setShareStateProvider: (fn: ShareStateProvider) => void
}

Example Usage

sdk.setShareStateProvider(async () => {
  return {
    path: "/path/to/share",
    params: { "foo": "bar" }
  };
});

sdk.setShareStateProvider(async () => {
  return {
    path: window.location.pathname,
    params: window.location.search
  };
});

The path and params provided by the function given to setShareStateProvider will be added to the copied mini app URL which will be the homeURL when opened via the launcher and the embed URL when opened via a cast_embed (obtained from sdk.context.location.type).

---

⚠️ ON HOLD: Implementing this is on hold since there are security implications to consider on the host to mini app communication that fall outside of the current SDK pattern.

[vrypan]

I'm not 100% sure I understand the use case.

1. Is sdk.setShareStateProvider expected to be called after sdk.actions.ready() and before sdk.actions.addFrame() in order to change the url of the frame a user adds to their favorites?
2. If it is expected to only affect addFrame, why not make ShareState a parameter to addFrame()?

[gabrielayuso]

It affects this:

(UX needs to be improved)

[vrypan]

Hmm.. Actually regarding "Copy link", I really need a way to get to the mini app url some times. For example, when viewing a Mini App blog post, like the ones in https://warpcast.com/miniapps/Z49hjQNzoyGo/blogvrypannet

But in the blog post case, being able to copy a "deep link" to the exact post is also great!

[darrylyeo]

I like it. Maybe call it setShareUrlResolver, match property names with those of native URL objects, and make the search params work with anything you'd ordinarily pass to new URLSearchParams():

type ShareUrl = {
  pathname?: string
  searchParams?: URLSearchParams | ConstructorParameters<typeof URLSearchParams>[0]
}

type ShareUrlResolver = () => (ShareUrl | Promise<ShareUrl>)

type FrameSDK = {
 // ...
 setShareUrlResolver: (fn: ShareUrlResolver) => void
}