@app-oracle/insights
v0.3.0
Published
SDK for generating feedback deep links via App Oracle
Maintainers
waylanReadme
Insights by App Oracle
A lightweight server-side SDK for generating secure deep links into the Audience Insights World mini app.
Collect feedback and reviews enriched with contextual data to support better business decisions. Every signed link cryptographically ties a response to the user experience in your app.
Installation
npm install @app-oracle/insightsQuick Start
import { Insights } from '@app-oracle/insights';
const APP_VERSION = '1.2.3';
const insights = new Insights({
apiKey: process.env.APP_ORACLE_API_KEY!,
});
const result = await insights.getFeedbackLink({
appVersion: APP_VERSION,
wallet: '0x1234567890abcdef',
metadata: {
level: 12,
itemsCollected: 6,
highScore: 32028,
joined: joinDate,
},
});
console.log(result.url);
// https://world.org/mini-app?app_id=abc123&path=/leave-feedback/def456Server-side only. Always store your API key in environment variables and call this SDK from your backend. Never expose your key in client-side code.
How It Works
1. Install Audience Insights and register your app.
Add your app inside the Audience Insights Mini App. Then verify ownership by adding a custom meta tag to your site's <head>. Full instructions are available on the Account page.
2. Grab your API key. Once verified, Audience Insights provides an API key. Use this to initialise the SDK on your server.
3. Wire up a feedback button. Add an async "Leave Feedback" button to your frontend. On tap, it calls a server-side function that uses the Insights SDK to generate a signed deep link and returns it to the client.
4. Deep link the user. The client opens the returned URL, taking the user directly into Audience Insights. They leave feedback and optionally submit an app review, then get linked back to your app.
API Reference
getFeedbackLink(options)
Generate a signed deep link for collecting feedback, with optional wallet verification and app review prompting.
const result = await insights.getFeedbackLink({
appVersion: APP_VERSION,
wallet: '0x1234567890abcdef',
metadata: {
swaps: swapCount,
trades: tradesCount,
joinDate: dateJoined,
proUser: true,
},
});Options
| Parameter | Type | Required | Description |
|---|---|---|---|
| appVersion | string | Yes | The current version of your app (e.g. "1.0.0"). Used to scope feedback and reviews to a specific release, enabling per-version analysis and trend tracking. |
| wallet | string | No | The user's wallet address. Hashed with SHA-256 before transmission. Providing a wallet verifies that the person leaving feedback is the same authenticated user in your app. |
| metadata | UserMetadata | No | Up to 4 key-value pairs attached to the feedback record. Use this to surface the context behind a user's sentiment — activity levels, feature usage, subscription status, and so on. |
| requestAppReview | boolean | No | Prompt the user for an app review in addition to feedback. Defaults to true when a wallet is provided. Reviews are shown on the Audience Insights Discovery page and improve your app's ranking. |
| redirectUrl | string | No | A deep link to return the user to after they submit feedback. Falls back to your app's homepage if not set. |
Response
interface DeepLinkResponse {
url: string; // The signed deep link to open on the client
expiresAt?: string; // Link expiry timestamp, if applicable
}Metadata
Attach up to 4 key-value pairs to any feedback or review link. Metadata is stored alongside each response, giving you the context you need to segment feedback by user behaviour, feature area, or account attributes.
type UserMetadata = Record<string, string | number | boolean | Date | null>;const result = await insights.getFeedbackLink({
appVersion: APP_VERSION,
metadata: {
swaps: swapCount,
trades: tradesCount,
joinDate: dateJoined,
proUser: true,
},
});License
MIT