You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- [List of frame notification tokens](https://docs.neynar.com/reference/fetch-notification-tokens)
31
-
</Step>
32
-
33
-
<Steptitle="Locate the Neynar Frame Events Webhook URL">
34
-
The Neynar mini app events webhook URL is on the Neynar app page. Navigate to [dev.neynar.com/app](https://dev.neynar.com/app) and then click on the app.
35
-
36
-
It should be in this format: `https://api.neynar.com/f/app/<your_client_id>/event`
37
-
38
-
See the highlighted URL in the image below.
39
-
40
-
**NEED IMAGE**
41
-
42
-
</Step>
43
-
44
-
<Steptitle="Set the Webhook URL in Your Mini App Manifest">
45
-
Frame servers must provide a JSON manifest file on their domain at the well-known URI, for example `https://your-frame-domain.com/.well-known/farcaster.json`.
46
-
47
-
Set the Neynar frame events URL as the `webhookUrl` in the Frame Config object inside the manifest. Here's an example manifest:
Frame manifest caching: Farcaster clients might have your mini app manifest cached and would only get updated on a periodic basis.
70
-
</Warning>
71
-
72
-
<Tip>
73
-
If you're using Farcaster to test, you can go to their Settings > Developer Tools > Domains, put in your Frame URL and hit the Check domain status to force a refresh.
74
-
</Tip>
75
-
</Step>
76
-
</Steps>
77
-
78
-
## Prompt Users to Add Your Mini App
79
-
80
-
<Steps>
81
-
<Steptitle="Install @neynar/react">
82
-
Install the Neynar React package to access the Mini App components:
83
-
84
-
```shell
85
-
npm install @neynar/react
86
-
```
87
-
</Step>
88
-
89
-
<Steptitle="Set up the MiniAppProvider Context Provider">
90
-
Wrap your app with the `MiniAppProvider` component to enable Mini App functionality:
91
-
92
-
```javascript
93
-
import { MiniAppProvider } from'@neynar/react';
94
-
95
-
exportdefaultfunctionApp() {
96
-
return (
97
-
<MiniAppProvider>
98
-
{/* Your app components */}
99
-
</MiniAppProvider>
100
-
);
101
-
}
102
-
```
103
-
</Step>
104
-
105
-
<Steptitle="Prompt the User to Add Your Mini App">
106
-
Use the `useMiniApp` hook to prompt users to add your Mini App:
107
-
108
-
```javascript
109
-
import { useMiniApp } from'@neynar/react';
110
-
111
-
exportdefaultfunctionHomePage() {
112
-
const { isSDKLoaded, addMiniApp } =useMiniApp();
113
-
114
-
consthandleAddMiniApp=async () => {
115
-
if (!isSDKLoaded) return;
116
-
117
-
constresult=awaitaddMiniApp();
118
-
if (result.added&&result.notificationDetails) {
119
-
// Mini app was added and notifications were enabled
If `added` is **true** and `notificationDetails` is a valid object, then the client should have called POST to the Neynar frame events webhook URL with the same details.
154
-
155
-
Neynar will manage all mini app add/remove & notifications enabled/disabled events delivered on this events webhook.
156
-
157
-
#### Alternative: Using the Mini App SDK directly
158
-
159
-
If you prefer to use the Mini App SDK directly instead of the Neynar React components:
160
-
161
-
```shell
162
-
yarn add @farcaster/frame-sdk
45
+
break;
46
+
47
+
case"miniapp_removed":
48
+
// Delete notification details
49
+
awaitdeleteUserNotificationDetails(fid);
50
+
break;
51
+
52
+
case"notifications_enabled":
53
+
// Save new notification details and send confirmation
| notificationId | string | Yes | Identifier that is combined with the FID to form an idempotency key. When the user opens the Mini App from the notification this ID will be included in the context object. | Maximum length of 128 characters |
79
+
| title | string | Yes | Title of the notification. | Max length 32 characters |
80
+
| body | string | Yes | Body of the notification. | Max length 128 characters. |
81
+
| targetUrl | string | Yes | URL to open when the user clicks the notification. | Max length 1024 characters.<br />Must be on the same domain as the Mini App. |
82
+
| tokens | string[]| Yes | Array of notification tokens to send to. | Max 100 tokens. |
169
83
170
-
const result =awaitsdk.actions.addFrame();
171
-
```
172
84
173
-
## Send Notifications to Users
85
+
####Send Notification Response Schema
174
86
175
-
Notifications can be broadcast to all your mini app users with notifications enabled or to a limited set of FIDs. Notifications can also be filtered so that only users meeting certain criteria receive the notification.
176
87
177
-
The `target_fids` parameter is the starting point for all filtering. Pass an empty array for `target_fids` to start with the set of all FIDs with notifications enabled for your app, or manually define `target_fids` to list specific FIDs.
| successfulTokens | string[]| Yes | Tokens for which the notification succeeded. |
91
+
| invalidTokens | string[]| Yes | Tokens which are no longer valid and should never be used again. This could happen if the user disabled notifications but for some reason the Mini App server has no record of it. |
92
+
| rateLimitedTokens | string[]| Yes | Tokens for which the rate limit was exceeded. The Mini App server can try later. |
178
93
179
-
<Steps>
180
-
<Steptitle="Target Users via the Neynar Dev Portal">
181
-
The [Neynar dev portal](https://dev.neynar.com) offers the same functionality as the API for broadcasting notifications. Navigate to your app and click the "Mini App" tab. Once your mini app is configured with your Neynar webhook URL and users have enabled notifications for your mini app, you'll see a "Broadcast Notification" section with an expandable filters section.
182
94
183
-
**Neynar mini app Broadcast Notification panel**
184
-
</Step>
185
95
186
-
<Steptitle="Target Users via the API">
187
-
The following example uses the [@neynar/nodejs-sdk](https://github.com/neynarxyz/nodejs-sdk) to send notifications to users and includes a set of filtering criteria:
96
+
## Events
188
97
189
-
```ts
190
-
const targetFids = []; // target all relevant users
191
-
const filters = {
192
-
exclude_fids: [420, 69], // do not send to these FIDs
193
-
following_fid: 3, // only send to users following this FID
194
-
minimum_user_score: 0.5, // only send to users with score >= this value
195
-
near_location: { // only send to users near a certain point
196
-
latitude: 34.052235,
197
-
longitude: -118.243683,
198
-
radius: 50000, // distance in meters from the lat/log point (optional, defaults to 50km)
199
-
}
200
-
};
98
+
Mini App events use the following object structure:
***`notificationDetails.url`**: URL that the app should call to send a notification.
102
+
***`notificationDetails.token`**: A secret token generated by the Farcaster App and shared with the Notification Server. A token is unique for each (Farcaster Client, Mini App, user Fid) tuple.
212
103
213
-
Additional documentation on the API and its body parameters can be found at [publish-frame-notifications](https://docs.neynar.com/reference/publish-frame-notifications).
214
-
</Step>
215
-
</Steps>
104
+
The optional `notificationDetails` object provides the `token` and `url` if the client equates adding to enabling notifications.
216
105
217
-
### Step 4: Check analytics
106
+
### `miniapp_added`
218
107
219
-
Notification analytics will automatically show in your developer portal once you start using Neynar for frame notifications.
108
+
Sent when the user adds the Mini App to their Farcaster client (whether or not it was triggered by an `addMiniApp()` prompt).
<Accordiontitle="How do I determine if the user has already added my Frame?">
122
+
### `miniapp_removed`
234
123
235
-
When using the `MiniAppProvider` context provider, you can check the `context` object from the `useMiniApp()` hook which contains the `added` boolean and `notificationDetails` object. More details in [Frame Core Types](https://github.com/farcasterxyz/frames/blob/main/packages/frame-core/src/types.ts#L58-L62)
236
-
</Accordion>
124
+
Sent when a user removes the Mini App, which means that any notification tokens for that FID and client app (based on signer requester) should be considered invalid:
237
125
238
-
<Accordiontitle="What happens if I send a notification via API to a user who has revoked notification permission?">
239
126
240
-
To avoid getting rate-limited by mini app clients, Neynar will filter out sending notifications to disabled tokens.
241
-
</Accordion>
127
+
```json miniapp_removed_payload
128
+
{
129
+
"event": "miniapp_removed"
130
+
}
131
+
```
242
132
243
-
<Accordiontitle="How do I fetch the notification tokens, URLs, and their status?">
133
+
### `notifications_enabled`
244
134
245
-
The [fetch notification tokens API](/reference/fetch-notification-tokens) provides access to the underlying data.
246
-
</Accordion>
135
+
Sent when a user enables notifications (e.g. after disabling them). The payload includes a new `token` and `url`:
Check out this tutorial: [Debug Notifications](https://docs.neynar.com/docs/debug-notifications)
250
-
</Accordion>
147
+
### `notifications_disabled`
251
148
252
-
<Accordiontitle="Who should I reach out to if I am experiencing additional issues or have questions?">
253
-
Reach out to the [Neynar Community Slack channel](https://neynar.com/slack)
254
-
</Accordion>
149
+
Sent when a user disables notifications from, e.g., a settings panel in the client app. Any notification tokens for that FID and client app (based on signer requester) should be considered invalid:
0 commit comments