Skip to content

Commit 06ed934

Browse files
hughescoinhughescoin
committed
use cards and paramfields
1 parent 43d2046 commit 06ed934

1 file changed

Lines changed: 280 additions & 57 deletions

File tree

‎docs/mini-apps/core-concepts/context.mdx‎

Lines changed: 280 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,6 @@ When your app is opened it can access information about the session from `sdk.co
1313
- `client`: Host platform and device data
1414
- `features`: Availability and state of features in the current client
1515

16-
17-
1816
<Panel>
1917
Context Types
2018
```ts MiniAppContextTypes.ts
@@ -120,22 +118,47 @@ export default function Profile() {
120118

121119
The `sdk.context` object contains four main components that provide information about the app session:
122120

123-
<AccordionGroup>
124-
<Accordion title="User Object">
121+
## User Object
122+
125123
Contains the user's profile information. This data shouldn't be used for authentication or sensitive actions because its passed by the application.
126124

127-
**Properties:**
128-
- **fid** `number`: Unique Farcaster identifier for the user
129-
- **username** `string?`: Handle without @ symbol
130-
- **displayName** `string?`: User's chosen display name
131-
- **pfpUrl** `string?`: Profile picture URL
132-
- **bio** `string?`: User's biography text
133-
- **location** `object?`: User's location information
134-
- **placeId** `string`: Google Places ID
135-
- **description** `string`: Human-readable location description
136-
137-
**Example:**
138-
```typescript
125+
<Card>
126+
<ParamField path="fid" type="number" required>
127+
Unique Farcaster identifier for the user.
128+
</ParamField>
129+
130+
<ParamField path="username" type="string">
131+
Handle without @ symbol.
132+
</ParamField>
133+
134+
<ParamField path="displayName" type="string">
135+
User's chosen display name.
136+
</ParamField>
137+
138+
<ParamField path="pfpUrl" type="string">
139+
Profile picture URL.
140+
</ParamField>
141+
142+
<ParamField path="bio" type="string">
143+
User's biography text.
144+
</ParamField>
145+
146+
<ParamField path="location" type="object">
147+
User's location information.
148+
</ParamField>
149+
150+
<ParamField path="location.placeId" type="string">
151+
Google Places ID.
152+
</ParamField>
153+
154+
<ParamField path="location.description" type="string">
155+
Human-readable location description.
156+
</ParamField>
157+
158+
159+
</Card>
160+
161+
```json user.json
139162
{
140163
"fid": 6841,
141164
"username": "deodad",
@@ -148,21 +171,87 @@ Contains the user's profile information. This data shouldn't be used for authent
148171
}
149172
}
150173
```
151-
</Accordion>
174+
## Location Object
152175

153-
<Accordion title="Location Object">
154176
Contains information about the context from which the Mini App was launched. This helps you understand how users discovered and accessed your app.
155177

156-
**Location Types:**
157-
- **cast_embed**: Launched from a cast where your app is embedded
158-
- **cast_share**: Launched when a user shared a cast to your app
159-
- **notification**: Launched from a notification triggered by your app
160-
- **launcher**: Launched directly from the client app catalog
161-
- **channel**: Launched from within a specific Farcaster channel
162-
- **open_miniapp**: Launched from another Mini App
163-
164-
**Cast Embed Example:**
165-
```typescript
178+
#### MiniAppUser
179+
180+
<Card>
181+
<ParamField path="fid" type="number" required>
182+
Unique Farcaster identifier for the user.
183+
</ParamField>
184+
185+
<ParamField path="username" type="string">
186+
User's handle without @ symbol.
187+
</ParamField>
188+
189+
<ParamField path="displayName" type="string">
190+
User's chosen display name.
191+
</ParamField>
192+
193+
<ParamField path="pfpUrl" type="string">
194+
Profile picture URL.
195+
</ParamField>
196+
</Card>
197+
198+
#### MiniAppCast
199+
200+
<Card>
201+
<ParamField path="author" type="MiniAppUser" required>
202+
Information about the cast author.
203+
</ParamField>
204+
205+
<ParamField path="hash" type="string" required>
206+
Cast hash identifier.
207+
</ParamField>
208+
209+
<ParamField path="parentHash" type="string">
210+
If this is a reply, the hash of the parent cast.
211+
</ParamField>
212+
213+
<ParamField path="parentFid" type="number">
214+
If this is a reply, the FID of the parent cast author.
215+
</ParamField>
216+
217+
<ParamField path="timestamp" type="number">
218+
Unix timestamp in milliseconds when the cast was created.
219+
</ParamField>
220+
221+
<ParamField path="mentions" type="MiniAppUser[]">
222+
Array of users mentioned in the cast.
223+
</ParamField>
224+
225+
<ParamField path="text" type="string" required>
226+
Cast text content.
227+
</ParamField>
228+
229+
<ParamField path="embeds" type="string[]">
230+
Array of embed URLs in the cast.
231+
</ParamField>
232+
233+
<ParamField path="channelKey" type="string">
234+
Channel where the cast was posted.
235+
</ParamField>
236+
</Card>
237+
238+
#### CastEmbedLocationContext
239+
240+
<Card>
241+
<ParamField path="type" type="'cast_embed'" required>
242+
Indicates the Mini App was launched from a cast where it is an embed.
243+
</ParamField>
244+
245+
<ParamField path="embed" type="string" required>
246+
The embed URL.
247+
</ParamField>
248+
249+
<ParamField path="cast" type="MiniAppCast" required>
250+
Cast information containing the embed.
251+
</ParamField>
252+
</Card>
253+
254+
```json cast_embed.json
166255
{
167256
"type": "cast_embed",
168257
"embed": "https://myapp.example.com",
@@ -182,8 +271,42 @@ Contains information about the context from which the Mini App was launched. Thi
182271
}
183272
```
184273

185-
**Notification Example:**
186-
```typescript
274+
#### CastShareLocationContext
275+
276+
<Card>
277+
<ParamField path="type" type="'cast_share'" required>
278+
Indicates the Mini App was launched when a user shared a cast to your app.
279+
</ParamField>
280+
281+
<ParamField path="cast" type="MiniAppCast" required>
282+
The cast that was shared to your app.
283+
</ParamField>
284+
</Card>
285+
286+
#### NotificationLocationContext
287+
288+
<Card>
289+
<ParamField path="type" type="'notification'" required>
290+
Indicates the Mini App was launched from a notification.
291+
</ParamField>
292+
293+
<ParamField path="notification" type="object" required>
294+
Notification details.
295+
<ParamField path="notification.notificationId" type="string" required>
296+
Unique notification identifier.
297+
</ParamField>
298+
<ParamField path="notification.title" type="string" required>
299+
Notification title.
300+
</ParamField>
301+
<ParamField path="notification.body" type="string" required>
302+
Notification body text.
303+
</ParamField>
304+
</ParamField>
305+
</Card>
306+
307+
308+
309+
```json notification.json
187310
{
188311
"type": "notification",
189312
"notification": {
@@ -193,26 +316,121 @@ Contains information about the context from which the Mini App was launched. Thi
193316
}
194317
}
195318
```
196-
</Accordion>
197319

198-
<Accordion title="Client Object">
320+
#### LauncherLocationContext
321+
322+
<Card>
323+
<ParamField path="type" type="'launcher'" required>
324+
Indicates the Mini App was launched directly by the client app outside of a context.
325+
</ParamField>
326+
</Card>
327+
328+
#### ChannelLocationContext
329+
330+
<Card>
331+
<ParamField path="type" type="'channel'" required>
332+
Indicates the Mini App was launched from within a specific Farcaster channel.
333+
</ParamField>
334+
335+
<ParamField path="channel" type="object" required>
336+
Channel details.
337+
</ParamField>
338+
339+
<ParamField path="channel.key" type="string" required>
340+
Channel key identifier.
341+
</ParamField>
342+
343+
<ParamField path="channel.name" type="string" required>
344+
Channel name.
345+
</ParamField>
346+
347+
<ParamField path="channel.imageUrl" type="string">
348+
Channel profile image URL.
349+
</ParamField>
350+
351+
</Card>
352+
353+
#### OpenMiniAppLocationContext
354+
355+
<Card>
356+
<ParamField path="type" type="'open_miniapp'" required>
357+
Indicates the Mini App was launched from another Mini App.
358+
</ParamField>
359+
360+
<ParamField path="referrerDomain" type="string" required>
361+
The domain of the Mini App that opened the current app.
362+
</ParamField>
363+
</Card>
364+
365+
**Location Types:**
366+
- **`cast_embed`**: Launched from a cast where your app is embedded
367+
- **`cast_share`**: Launched when a user shared a cast to your app
368+
- **`notification`**: Launched from a notification triggered by your app
369+
- **`launcher`**: Launched directly from the client app catalog
370+
- **`channel`**: Launched from within a specific Farcaster channel
371+
- **`open_miniapp`**: Launched from another Mini App
372+
373+
## Client Object
374+
199375
Contains details about the Farcaster client running your Mini App. This data should be considered untrusted.
200376

201-
**Properties:**
202-
- **platformType** `'web' | 'mobile'?`: Platform where the app is running
203-
- **clientFid** `number`: Self-reported FID of the client (e.g., 9152 for Warpcast)
204-
- **added** `boolean`: Whether the user has added your Mini App to their client
205-
- **safeAreaInsets** `object?`: Screen insets to avoid navigation elements
206-
- **top** `number`: Top safe area inset in pixels
207-
- **bottom** `number`: Bottom safe area inset in pixels
208-
- **left** `number`: Left safe area inset in pixels
209-
- **right** `number`: Right safe area inset in pixels
210-
- **notificationDetails** `object?`: Notification configuration if enabled
211-
- **url** `string`: Endpoint for sending notifications
212-
- **token** `string`: Authentication token for notifications
213-
214-
**Example:**
215-
```typescript
377+
#### SafeAreaInsets
378+
379+
<Card>
380+
<ParamField path="top" type="number" required>
381+
Top safe area inset in pixels.
382+
</ParamField>
383+
384+
<ParamField path="bottom" type="number" required>
385+
Bottom safe area inset in pixels.
386+
</ParamField>
387+
388+
<ParamField path="left" type="number" required>
389+
Left safe area inset in pixels.
390+
</ParamField>
391+
392+
<ParamField path="right" type="number" required>
393+
Right safe area inset in pixels.
394+
</ParamField>
395+
</Card>
396+
397+
#### MiniAppNotificationDetails
398+
399+
<Card>
400+
<ParamField path="url" type="string" required>
401+
Endpoint for sending notifications.
402+
</ParamField>
403+
404+
<ParamField path="token" type="string" required>
405+
Authentication token for notifications.
406+
</ParamField>
407+
</Card>
408+
409+
#### ClientContext
410+
411+
<Card>
412+
<ParamField path="platformType" type="'web' | 'mobile'">
413+
Platform where the app is running.
414+
</ParamField>
415+
416+
<ParamField path="clientFid" type="number" required>
417+
Self-reported FID of the client (e.g., 9152 for Farcaster).
418+
</ParamField>
419+
420+
<ParamField path="added" type="boolean" required>
421+
Whether the user has added your Mini App to their client.
422+
</ParamField>
423+
424+
<ParamField path="safeAreaInsets" type="SafeAreaInsets">
425+
Screen insets to avoid navigation elements that obscure the view.
426+
</ParamField>
427+
428+
<ParamField path="notificationDetails" type="MiniAppNotificationDetails">
429+
Notification configuration if enabled.
430+
</ParamField>
431+
</Card>
432+
433+
```json client.json
216434
{
217435
"platformType": "mobile",
218436
"clientFid": 9152,
@@ -229,23 +447,28 @@ Contains details about the Farcaster client running your Mini App. This data sho
229447
}
230448
}
231449
```
232-
</Accordion>
233450

234-
<Accordion title="Features Object">
451+
## Features Object
452+
235453
Indicates which platform features are available and their current state in the client.
236454

237-
**Properties:**
238-
- **haptics** `boolean`: Whether haptic feedback is supported on the current platform
239-
- **cameraAndMicrophoneAccess** `boolean?`: Whether camera and microphone permissions have been granted and stored for this mini app
455+
#### ClientFeatures
456+
457+
<Card>
458+
<ParamField path="haptics" type="boolean" required>
459+
Whether haptic feedback is supported on the current platform.
460+
</ParamField>
461+
462+
<ParamField path="cameraAndMicrophoneAccess" type="boolean">
463+
Whether camera and microphone permissions have been granted and stored for this mini app.
464+
</ParamField>
465+
</Card>
240466

241-
**Example:**
242-
```typescript
467+
```json features.json
243468
{
244469
"haptics": true,
245470
"cameraAndMicrophoneAccess": true
246471
}
247472
```
248473

249-
**Usage Note:** For more detailed capability detection, use the `sdk.getCapabilities()` method which returns specific SDK methods supported by the host.
250-
</Accordion>
251-
</AccordionGroup>
474+
<Note>For more detailed capability detection, use the `sdk.getCapabilities()` method which returns specific SDK methods supported by the host.</Note>

0 commit comments

Comments
 (0)