diff --git a/docs/mini-apps/core-concepts/navigation.mdx b/docs/mini-apps/core-concepts/navigation.mdx deleted file mode 100644 index bbdef16f9..000000000 --- a/docs/mini-apps/core-concepts/navigation.mdx +++ /dev/null @@ -1,324 +0,0 @@ ---- -title: Navigation -description: Gracefully navigate users from your mini app through the Base app and to external links. ---- - -## Overview - -Use the functions provided by the `@farcaster/miniapp-sdk` to navigate users from your mini app throughout the Base app and to external links with a native user experience. - - - - -```md -# Mini App Navigation Pattern Migration - -## Context -I'm building a Farcaster Mini App on Base. Mini Apps must use official SDK functions for all navigation and external interactions to ensure cross-client compatibility. - -## Your Task -Review this file and refactor any incorrect navigation patterns to use the correct SDK actions. - -## Incorrect Patterns to Fix - -### Don't Use: -- Direct HTML links: ``, `` -- Window navigation: `window.open()` -- Static URLs or deeplinks to Farcaster -- Client-specific URLs (like Warpcast URLs) -- Composer intent URLs: `https://farcaster.com/~/compose?text=...` -- Direct cast URLs for viewing - -## Correct SDK Actions - -### For Farcaster SDK (`@farcaster/miniapp-sdk`) -1. **External Links:** Use `sdk.actions.openUrl(url)` -2. **Create Posts:** Use `sdk.actions.composeCast({ text, embeds })` -3. **View Casts:** Use `sdk.actions.viewCast(castUrl)` - -### For MiniKit (`@coinbase/onchainkit/minikit`) -1. **External Links:** Use `useOpenUrl()` hook -2. **Create Posts:** Use `useComposeCast()` hook -3. **View Casts:** Use `useViewCast()` hook - -## Migration Examples - -// BEFORE (Incorrect) -Visit Site - - -// AFTER (Correct - Farcaster SDK) -import { sdk } from '@farcaster/miniapp-sdk'; - - -// AFTER (Correct - MiniKit) -import { useOpenUrl } from '@coinbase/onchainkit/minikit'; -const openUrl = useOpenUrl(); - - -// BEFORE (Incorrect) -window.open('https://farcaster.com/~/compose?text=Check this out!') - -// AFTER (Correct - Farcaster SDK) -sdk.actions.composeCast({ - text: 'Check this out!', - embeds: [window.location.href] -}) - -// AFTER (Correct - MiniKit) -const { composeCast } = useComposeCast(); -composeCast({ - text: 'Check this out!', - embeds: [window.location.href] -}) - -``` - - - - - - -## External Navigation - -### Opening External URLs - - - - Use `sdk.actions.openUrl()` to safely open external websites in the client's in-app browser: - - ```typescript App.tsx highlight={5} - import { sdk } from '@farcaster/miniapp-sdk'; - - // Correct: Use SDK action - const openExternalSite = () => { - sdk.actions.openUrl('https://example.com'); - }; - - // Incorrect: Direct HTML link - // Visit Site - ``` - - - - Use [`useOpenUrl()`](/onchainkit/latest/components/minikit/hooks/useOpenUrl) to safely open external websites in the client's in-app browser: - - ```tsx components/ExternalLinks.tsx highlight={8 -10} - import { useOpenUrl } from '@coinbase/onchainkit/minikit'; - - export default function ExternalLinks() { - const openUrl = useOpenUrl(); - - return ( -
- - - -
- ); - } - - // Incorrect: Direct HTML link - // Visit Site - ``` - - - -### Composing Casts - - - - - Use `sdk.actions.composeCast()` instead of composer intent URLs: - - ```typescript App.tsx highlight={5-8} - import { sdk } from '@farcaster/miniapp-sdk'; - - // Correct: Use SDK action - const shareContent = () => { - sdk.actions.composeCast({ - text: 'Check out this Mini App!', - embeds: ['https://yourminiapp.com'] - }); - }; - - // Incorrect: Composer intent URLs - // window.open('https://farcaster.com/~/compose?text=...') - ``` - - - Use [`useComposeCast()`](/onchainkit/latest/components/minikit/hooks/useComposeCast) to open the native composer with prefilled content: - ```tsx components/ShareCast.tsx highlight={8-13} - import { useComposeCast } from '@coinbase/onchainkit/minikit'; - - export default function ShareCast() { - const { composeCast } = useComposeCast(); - - return ( - - ); - } - - // Incorrect: Composer intent URLs - // window.open('https://farcaster.com/~/compose?text=...') - ``` - - - -### Viewing Casts - - - - - Use `sdk.actions.viewCast()` instead of cast intent URLs: - - ```typescript App.tsx - import { sdk } from '@farcaster/miniapp-sdk'; - - // Correct: Use SDK action - const viewCast = () => { - sdk.actions.viewCast('https://base.app/post/0xffdec7c879aad726b5400d22ec8a89aaff6e0737'); - }; - ``` - - - - Use [`useViewCast()`](/onchainkit/latest/components/minikit/hooks/useViewCast) to open a specific cast by its hash: - ```tsx components/ViewCastButton.tsx highlight={4,7-9} - import { useViewCast } from '@coinbase/onchainkit/minikit'; - - export default function ViewCastButton() { - const viewCast = useViewCast('0x1234567890abcdef1234567890abcdef12345678'); - - return ( - - ); - } - ``` - - - -### Conditional Navigation - -If your mini app can be opened in the browser, implement conditional navigation to handle cases where mini app-specific functions (e.g., Compose Cast) are unavailable. - -```javascript ConditionalNavigation.tsx highlight={4, 8-13} -import { sdk } from 'farcaster/miniapp-sdk'; - -const ConditionalNavigation = () => { - const context = sdk.context; - - const handleNavigation = () => { - // Adapt behavior based on client capabilities - if (context.client.clientFid) { - sdk.actions.openUrl('https://app-specific-url.com'); - } else { - // Fallback for other clients - window.open('https://fallback-url.com', '_blank'); - } - }; - - return ( - - ); -}; -``` - -## Deeplinks - -Provide your users with direct access to Mini Apps, group messages, and DMs using our deeplinking schema. - -### Mini Apps - -Launch your mini app directly from external sources like websites, QR codes, or other applications. - -```HTML index.html - - Launch Mini App - -``` - - -### Chat Deeplinks - -#### Direct Messages (Users or Agents) - -Start a private conversation with a specific user or agent. - -```typescript DeeplinkDM.tsx - -``` - - -#### Group Messages - -Navigate users directly to a specific group chat conversation. - - - Users can only access group conversations they have been added to as members. - - -Getting the `conversationID`: - -```typescript agent.ts highlight={3,6,9} -agent.on('text', async (ctx) => { - // Get conversation ID - const conversationId = ctx.conversation.id; - - // Create deeplink to THIS conversation (not just the agent) - const groupDeeplink = `cbwallet://messaging/${conversationId}`; - - if (ctx.isGroup()) { - await ctx.sendText(`Share this group: ${groupDeeplink}`); - } -}); -``` - -Use the `conversationID` as a button: - -```typescript DeeplinkButton.tsx - -``` - -## Schema - -### Group Message Parameters - - - The unique identifier for an XMTP group conversation. - - -### Direct Message Parameters - - - The 0x address of the user or agent you want to chat with (in hex format, e.g., `0xabc...1234`). - - - -