@proveanything/smartlinks 1.4.0 → 1.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/docs/API_SUMMARY.md +2 -1
- package/dist/docs/ai-guide-template.md +241 -0
- package/docs/API_SUMMARY.md +2 -1
- package/docs/ai-guide-template.md +241 -0
- package/package.json +1 -1
package/dist/docs/API_SUMMARY.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Smartlinks API Summary
|
|
2
2
|
|
|
3
|
-
Version: 1.4.
|
|
3
|
+
Version: 1.4.1 | Generated: 2026-02-20T19:32:34.980Z
|
|
4
4
|
|
|
5
5
|
This is a concise summary of all available API functions and types.
|
|
6
6
|
|
|
@@ -18,6 +18,7 @@ For detailed guides on specific features:
|
|
|
18
18
|
- **[Theme Defaults](theme-defaults.md)** - Default theme values and presets
|
|
19
19
|
- **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
|
|
20
20
|
- **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
|
|
21
|
+
- **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
|
|
21
22
|
|
|
22
23
|
## API Namespaces
|
|
23
24
|
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
# AI Guide: Example App
|
|
2
|
+
|
|
3
|
+
<!-- CUSTOMIZE: Replace "Example App" and all content below with your app's specifics. -->
|
|
4
|
+
<!-- This file is consumed by AI orchestrators alongside public/app.manifest.json. -->
|
|
5
|
+
<!-- The manifest provides structured data; this file provides prose context and nuance. -->
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Purpose & Identity
|
|
10
|
+
|
|
11
|
+
<!-- CUSTOMIZE: Describe what your app does in 2-3 sentences. -->
|
|
12
|
+
|
|
13
|
+
The **Example App** is a template SmartLinks microapp that demonstrates all platform patterns including setup wizards, data imports, widget embedding, and analytics. It serves as a reference implementation for app authors building on the SmartLinks platform.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Setup Wizard Instructions
|
|
18
|
+
|
|
19
|
+
An AI orchestrator should follow these steps to configure the Example App for a collection. The structured questions and schema are in `app.manifest.json` under `setup`.
|
|
20
|
+
|
|
21
|
+
### Prerequisites
|
|
22
|
+
|
|
23
|
+
- The user must have **admin access** to the target collection.
|
|
24
|
+
- The `collectionId` and `appId` must be known (typically from URL context).
|
|
25
|
+
|
|
26
|
+
### Questions to Ask
|
|
27
|
+
|
|
28
|
+
Walk the user through each question defined in `setup.questions[]` of the manifest:
|
|
29
|
+
|
|
30
|
+
1. **App Title** (`appTitle`): Ask what the app should be called. Offer to auto-generate a suggestion using `SL.ai.chat.completions` if the user wants help (see `contentHints` in the manifest).
|
|
31
|
+
2. **Enable Notifications** (`enableNotifications`): Ask whether the app should send notifications to users.
|
|
32
|
+
|
|
33
|
+
<!-- CUSTOMIZE: Add app-specific guidance for each question. For example: -->
|
|
34
|
+
<!-- "If the user is setting up a competition, suggest a title like 'Win a [Product Name]!'" -->
|
|
35
|
+
<!-- "For plant passports, notifications are typically disabled." -->
|
|
36
|
+
|
|
37
|
+
### How to Save the Config
|
|
38
|
+
|
|
39
|
+
After collecting answers, validate against `setup.configSchema` and save:
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
await SL.appConfiguration.setConfig({
|
|
43
|
+
collectionId,
|
|
44
|
+
appId,
|
|
45
|
+
config: {
|
|
46
|
+
appTitle: "User's chosen title",
|
|
47
|
+
enableNotifications: false
|
|
48
|
+
},
|
|
49
|
+
admin: true // REQUIRED for admin operations
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Post-Setup Verification
|
|
54
|
+
|
|
55
|
+
After saving, confirm by reading the config back:
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
const saved = await SL.appConfiguration.getConfig({
|
|
59
|
+
collectionId,
|
|
60
|
+
appId,
|
|
61
|
+
admin: true
|
|
62
|
+
});
|
|
63
|
+
// Verify saved.appTitle and saved.enableNotifications match expectations
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Tell the user: "Your app is configured! You can adjust settings anytime by asking me to update the configuration."
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Import Instructions
|
|
71
|
+
|
|
72
|
+
The app supports bulk import of product-level configuration. The field definitions are in `app.manifest.json` under `import`.
|
|
73
|
+
|
|
74
|
+
### CSV Template
|
|
75
|
+
|
|
76
|
+
Generate or share this template with the user:
|
|
77
|
+
|
|
78
|
+
```csv
|
|
79
|
+
productId,appTitle,enableNotifications
|
|
80
|
+
prod_001,My First Product,true
|
|
81
|
+
prod_002,My Second Product,false
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
<!-- CUSTOMIZE: Add real-world examples relevant to your app. -->
|
|
85
|
+
|
|
86
|
+
### Field Validation Rules
|
|
87
|
+
|
|
88
|
+
| Field | Type | Required | Validation |
|
|
89
|
+
| --------------------- | ------- | -------- | ------------------------------------- |
|
|
90
|
+
| `productId` | string | ✅ | Must be a valid SmartLinks product ID |
|
|
91
|
+
| `appTitle` | string | ✅ | Non-empty string |
|
|
92
|
+
| `enableNotifications` | boolean | ❌ | Defaults to `false` |
|
|
93
|
+
|
|
94
|
+
<!-- CUSTOMIZE: Add app-specific validation rules. For example: -->
|
|
95
|
+
<!-- "For plant passports: botanicalName must be in Latin binomial format." -->
|
|
96
|
+
|
|
97
|
+
### API Call Sequence
|
|
98
|
+
|
|
99
|
+
For each row in the CSV:
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
await SL.appConfiguration.setConfig({
|
|
103
|
+
collectionId,
|
|
104
|
+
productId: row.productId, // From CSV
|
|
105
|
+
appId,
|
|
106
|
+
config: {
|
|
107
|
+
appTitle: row.appTitle,
|
|
108
|
+
enableNotifications: row.enableNotifications ?? false
|
|
109
|
+
},
|
|
110
|
+
admin: true
|
|
111
|
+
});
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Error Handling
|
|
115
|
+
|
|
116
|
+
- If a `productId` is invalid, log the error and continue with the next row.
|
|
117
|
+
- After processing all rows, report a summary: `"Imported X of Y products successfully. Z failed."`.
|
|
118
|
+
- For failed rows, list the product ID and error message so the user can fix the data.
|
|
119
|
+
|
|
120
|
+
### Cross-App Import
|
|
121
|
+
|
|
122
|
+
When importing data for multiple apps simultaneously:
|
|
123
|
+
|
|
124
|
+
1. Fetch `app.manifest.json` from each app.
|
|
125
|
+
2. Merge `import.fields` arrays (prefix field names with app name if there are conflicts).
|
|
126
|
+
3. Generate a combined CSV template.
|
|
127
|
+
4. For each row, split into separate payloads per app and call each app's `saveWith.method`.
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Widget Embedding Guide
|
|
132
|
+
|
|
133
|
+
### Available Widgets
|
|
134
|
+
|
|
135
|
+
| Widget | Description | Sizes |
|
|
136
|
+
| --------------- | ------------------------------------------ | ------------------------ |
|
|
137
|
+
| `ExampleWidget` | Demo widget showing SmartLinks integration | compact, standard, large |
|
|
138
|
+
|
|
139
|
+
<!-- CUSTOMIZE: List all widgets your app exports. -->
|
|
140
|
+
|
|
141
|
+
### Props Reference
|
|
142
|
+
|
|
143
|
+
All widgets receive `SmartLinksWidgetProps`:
|
|
144
|
+
|
|
145
|
+
| Prop | Type | Required | Description |
|
|
146
|
+
| ----------------- | -------------- | -------- | --------------------------------------- |
|
|
147
|
+
| `collectionId` | string | ✅ | Collection context |
|
|
148
|
+
| `appId` | string | ✅ | App identifier |
|
|
149
|
+
| `SL` | SmartLinks SDK | ✅ | Pre-initialized SDK instance |
|
|
150
|
+
| `productId` | string | ❌ | Product context |
|
|
151
|
+
| `proofId` | string | ❌ | Proof context |
|
|
152
|
+
| `user` | object | ❌ | Current user info |
|
|
153
|
+
| `onNavigate` | function | ❌ | Navigation callback |
|
|
154
|
+
| `publicPortalUrl` | string | ❌ | URL to full app for deep linking |
|
|
155
|
+
| `size` | string | ❌ | `"compact"`, `"standard"`, or `"large"` |
|
|
156
|
+
| `lang` | string | ❌ | Language code (e.g., `"en"`) |
|
|
157
|
+
| `translations` | object | ❌ | Translation overrides |
|
|
158
|
+
|
|
159
|
+
### Example Code
|
|
160
|
+
|
|
161
|
+
```tsx
|
|
162
|
+
import { ExampleWidget } from '@my-app/widgets';
|
|
163
|
+
|
|
164
|
+
<ExampleWidget
|
|
165
|
+
collectionId="col_123"
|
|
166
|
+
appId="example-app"
|
|
167
|
+
SL={SL}
|
|
168
|
+
size="standard"
|
|
169
|
+
onNavigate={(path) => router.push(path)}
|
|
170
|
+
/>
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
<!-- CUSTOMIZE: Show real widget usage with app-specific props. -->
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Tunable Settings
|
|
178
|
+
|
|
179
|
+
These settings can be adjusted after initial setup without reconfiguring everything. The AI can modify them in response to user requests like "turn off notifications" or optimization suggestions.
|
|
180
|
+
|
|
181
|
+
| Setting | Type | Description |
|
|
182
|
+
| --------------------- | ------- | ------------------------------ |
|
|
183
|
+
| `enableNotifications` | boolean | Toggle notifications on or off |
|
|
184
|
+
|
|
185
|
+
<!-- CUSTOMIZE: List all tunable fields with guidance on when to change them. -->
|
|
186
|
+
|
|
187
|
+
To update a tunable setting:
|
|
188
|
+
|
|
189
|
+
```typescript
|
|
190
|
+
// 1. Read current config
|
|
191
|
+
const current = await SL.appConfiguration.getConfig({ collectionId, appId, admin: true });
|
|
192
|
+
|
|
193
|
+
// 2. Merge the change
|
|
194
|
+
await SL.appConfiguration.setConfig({
|
|
195
|
+
collectionId,
|
|
196
|
+
appId,
|
|
197
|
+
config: { ...current, enableNotifications: true },
|
|
198
|
+
admin: true
|
|
199
|
+
});
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Metrics & Analytics
|
|
205
|
+
|
|
206
|
+
### Tracked Interactions
|
|
207
|
+
|
|
208
|
+
| Interaction ID | Description |
|
|
209
|
+
| -------------- | --------------------------------------------- |
|
|
210
|
+
| `page-view` | Tracks each time a user views the public page |
|
|
211
|
+
|
|
212
|
+
<!-- CUSTOMIZE: List all interaction IDs your app tracks. -->
|
|
213
|
+
|
|
214
|
+
### KPIs
|
|
215
|
+
|
|
216
|
+
| KPI | How to Compute |
|
|
217
|
+
| ----------- | -------------------------------------------------------------------------------------- |
|
|
218
|
+
| Total Views | `SL.interactions.countsByOutcome(collectionId, { appId, interactionId: 'page-view' })` |
|
|
219
|
+
|
|
220
|
+
<!-- CUSTOMIZE: Add app-specific KPIs and interpretation guidance. -->
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## Troubleshooting
|
|
225
|
+
|
|
226
|
+
### Common Issues
|
|
227
|
+
|
|
228
|
+
| Issue | Cause | Fix |
|
|
229
|
+
| --------------------- | -------------------------- | ----------------------------------------------------- |
|
|
230
|
+
| Config save fails | Missing `admin: true` flag | Always include `admin: true` for admin operations |
|
|
231
|
+
| Widget doesn't render | Missing required props | Ensure `collectionId`, `appId`, and `SL` are provided |
|
|
232
|
+
| Import skips rows | Invalid `productId` | Verify product IDs exist in the collection |
|
|
233
|
+
| Theme not applied | Missing `?theme=` param | Check URL parameters or postMessage setup |
|
|
234
|
+
|
|
235
|
+
<!-- CUSTOMIZE: Add app-specific troubleshooting entries. -->
|
|
236
|
+
|
|
237
|
+
### Getting Help
|
|
238
|
+
|
|
239
|
+
- **SDK Docs**: `node_modules/@proveanything/smartlinks/docs/`
|
|
240
|
+
- **App Manifest**: `public/app.manifest.json`
|
|
241
|
+
- **Platform Guide**: `src/docs/smartlinks/about.md`
|
package/docs/API_SUMMARY.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Smartlinks API Summary
|
|
2
2
|
|
|
3
|
-
Version: 1.4.
|
|
3
|
+
Version: 1.4.1 | Generated: 2026-02-20T19:32:34.980Z
|
|
4
4
|
|
|
5
5
|
This is a concise summary of all available API functions and types.
|
|
6
6
|
|
|
@@ -18,6 +18,7 @@ For detailed guides on specific features:
|
|
|
18
18
|
- **[Theme Defaults](theme-defaults.md)** - Default theme values and presets
|
|
19
19
|
- **[Proof Claiming Methods](proof-claiming-methods.md)** - All methods for claiming/registering product ownership (NFC tags, serial numbers, auto-generated claims)
|
|
20
20
|
- **[App Data Storage](app-data-storage.md)** - User-specific and collection-scoped app data storage
|
|
21
|
+
- **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
|
|
21
22
|
|
|
22
23
|
## API Namespaces
|
|
23
24
|
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
# AI Guide: Example App
|
|
2
|
+
|
|
3
|
+
<!-- CUSTOMIZE: Replace "Example App" and all content below with your app's specifics. -->
|
|
4
|
+
<!-- This file is consumed by AI orchestrators alongside public/app.manifest.json. -->
|
|
5
|
+
<!-- The manifest provides structured data; this file provides prose context and nuance. -->
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Purpose & Identity
|
|
10
|
+
|
|
11
|
+
<!-- CUSTOMIZE: Describe what your app does in 2-3 sentences. -->
|
|
12
|
+
|
|
13
|
+
The **Example App** is a template SmartLinks microapp that demonstrates all platform patterns including setup wizards, data imports, widget embedding, and analytics. It serves as a reference implementation for app authors building on the SmartLinks platform.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Setup Wizard Instructions
|
|
18
|
+
|
|
19
|
+
An AI orchestrator should follow these steps to configure the Example App for a collection. The structured questions and schema are in `app.manifest.json` under `setup`.
|
|
20
|
+
|
|
21
|
+
### Prerequisites
|
|
22
|
+
|
|
23
|
+
- The user must have **admin access** to the target collection.
|
|
24
|
+
- The `collectionId` and `appId` must be known (typically from URL context).
|
|
25
|
+
|
|
26
|
+
### Questions to Ask
|
|
27
|
+
|
|
28
|
+
Walk the user through each question defined in `setup.questions[]` of the manifest:
|
|
29
|
+
|
|
30
|
+
1. **App Title** (`appTitle`): Ask what the app should be called. Offer to auto-generate a suggestion using `SL.ai.chat.completions` if the user wants help (see `contentHints` in the manifest).
|
|
31
|
+
2. **Enable Notifications** (`enableNotifications`): Ask whether the app should send notifications to users.
|
|
32
|
+
|
|
33
|
+
<!-- CUSTOMIZE: Add app-specific guidance for each question. For example: -->
|
|
34
|
+
<!-- "If the user is setting up a competition, suggest a title like 'Win a [Product Name]!'" -->
|
|
35
|
+
<!-- "For plant passports, notifications are typically disabled." -->
|
|
36
|
+
|
|
37
|
+
### How to Save the Config
|
|
38
|
+
|
|
39
|
+
After collecting answers, validate against `setup.configSchema` and save:
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
await SL.appConfiguration.setConfig({
|
|
43
|
+
collectionId,
|
|
44
|
+
appId,
|
|
45
|
+
config: {
|
|
46
|
+
appTitle: "User's chosen title",
|
|
47
|
+
enableNotifications: false
|
|
48
|
+
},
|
|
49
|
+
admin: true // REQUIRED for admin operations
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Post-Setup Verification
|
|
54
|
+
|
|
55
|
+
After saving, confirm by reading the config back:
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
const saved = await SL.appConfiguration.getConfig({
|
|
59
|
+
collectionId,
|
|
60
|
+
appId,
|
|
61
|
+
admin: true
|
|
62
|
+
});
|
|
63
|
+
// Verify saved.appTitle and saved.enableNotifications match expectations
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Tell the user: "Your app is configured! You can adjust settings anytime by asking me to update the configuration."
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Import Instructions
|
|
71
|
+
|
|
72
|
+
The app supports bulk import of product-level configuration. The field definitions are in `app.manifest.json` under `import`.
|
|
73
|
+
|
|
74
|
+
### CSV Template
|
|
75
|
+
|
|
76
|
+
Generate or share this template with the user:
|
|
77
|
+
|
|
78
|
+
```csv
|
|
79
|
+
productId,appTitle,enableNotifications
|
|
80
|
+
prod_001,My First Product,true
|
|
81
|
+
prod_002,My Second Product,false
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
<!-- CUSTOMIZE: Add real-world examples relevant to your app. -->
|
|
85
|
+
|
|
86
|
+
### Field Validation Rules
|
|
87
|
+
|
|
88
|
+
| Field | Type | Required | Validation |
|
|
89
|
+
| --------------------- | ------- | -------- | ------------------------------------- |
|
|
90
|
+
| `productId` | string | ✅ | Must be a valid SmartLinks product ID |
|
|
91
|
+
| `appTitle` | string | ✅ | Non-empty string |
|
|
92
|
+
| `enableNotifications` | boolean | ❌ | Defaults to `false` |
|
|
93
|
+
|
|
94
|
+
<!-- CUSTOMIZE: Add app-specific validation rules. For example: -->
|
|
95
|
+
<!-- "For plant passports: botanicalName must be in Latin binomial format." -->
|
|
96
|
+
|
|
97
|
+
### API Call Sequence
|
|
98
|
+
|
|
99
|
+
For each row in the CSV:
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
await SL.appConfiguration.setConfig({
|
|
103
|
+
collectionId,
|
|
104
|
+
productId: row.productId, // From CSV
|
|
105
|
+
appId,
|
|
106
|
+
config: {
|
|
107
|
+
appTitle: row.appTitle,
|
|
108
|
+
enableNotifications: row.enableNotifications ?? false
|
|
109
|
+
},
|
|
110
|
+
admin: true
|
|
111
|
+
});
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Error Handling
|
|
115
|
+
|
|
116
|
+
- If a `productId` is invalid, log the error and continue with the next row.
|
|
117
|
+
- After processing all rows, report a summary: `"Imported X of Y products successfully. Z failed."`.
|
|
118
|
+
- For failed rows, list the product ID and error message so the user can fix the data.
|
|
119
|
+
|
|
120
|
+
### Cross-App Import
|
|
121
|
+
|
|
122
|
+
When importing data for multiple apps simultaneously:
|
|
123
|
+
|
|
124
|
+
1. Fetch `app.manifest.json` from each app.
|
|
125
|
+
2. Merge `import.fields` arrays (prefix field names with app name if there are conflicts).
|
|
126
|
+
3. Generate a combined CSV template.
|
|
127
|
+
4. For each row, split into separate payloads per app and call each app's `saveWith.method`.
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## Widget Embedding Guide
|
|
132
|
+
|
|
133
|
+
### Available Widgets
|
|
134
|
+
|
|
135
|
+
| Widget | Description | Sizes |
|
|
136
|
+
| --------------- | ------------------------------------------ | ------------------------ |
|
|
137
|
+
| `ExampleWidget` | Demo widget showing SmartLinks integration | compact, standard, large |
|
|
138
|
+
|
|
139
|
+
<!-- CUSTOMIZE: List all widgets your app exports. -->
|
|
140
|
+
|
|
141
|
+
### Props Reference
|
|
142
|
+
|
|
143
|
+
All widgets receive `SmartLinksWidgetProps`:
|
|
144
|
+
|
|
145
|
+
| Prop | Type | Required | Description |
|
|
146
|
+
| ----------------- | -------------- | -------- | --------------------------------------- |
|
|
147
|
+
| `collectionId` | string | ✅ | Collection context |
|
|
148
|
+
| `appId` | string | ✅ | App identifier |
|
|
149
|
+
| `SL` | SmartLinks SDK | ✅ | Pre-initialized SDK instance |
|
|
150
|
+
| `productId` | string | ❌ | Product context |
|
|
151
|
+
| `proofId` | string | ❌ | Proof context |
|
|
152
|
+
| `user` | object | ❌ | Current user info |
|
|
153
|
+
| `onNavigate` | function | ❌ | Navigation callback |
|
|
154
|
+
| `publicPortalUrl` | string | ❌ | URL to full app for deep linking |
|
|
155
|
+
| `size` | string | ❌ | `"compact"`, `"standard"`, or `"large"` |
|
|
156
|
+
| `lang` | string | ❌ | Language code (e.g., `"en"`) |
|
|
157
|
+
| `translations` | object | ❌ | Translation overrides |
|
|
158
|
+
|
|
159
|
+
### Example Code
|
|
160
|
+
|
|
161
|
+
```tsx
|
|
162
|
+
import { ExampleWidget } from '@my-app/widgets';
|
|
163
|
+
|
|
164
|
+
<ExampleWidget
|
|
165
|
+
collectionId="col_123"
|
|
166
|
+
appId="example-app"
|
|
167
|
+
SL={SL}
|
|
168
|
+
size="standard"
|
|
169
|
+
onNavigate={(path) => router.push(path)}
|
|
170
|
+
/>
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
<!-- CUSTOMIZE: Show real widget usage with app-specific props. -->
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Tunable Settings
|
|
178
|
+
|
|
179
|
+
These settings can be adjusted after initial setup without reconfiguring everything. The AI can modify them in response to user requests like "turn off notifications" or optimization suggestions.
|
|
180
|
+
|
|
181
|
+
| Setting | Type | Description |
|
|
182
|
+
| --------------------- | ------- | ------------------------------ |
|
|
183
|
+
| `enableNotifications` | boolean | Toggle notifications on or off |
|
|
184
|
+
|
|
185
|
+
<!-- CUSTOMIZE: List all tunable fields with guidance on when to change them. -->
|
|
186
|
+
|
|
187
|
+
To update a tunable setting:
|
|
188
|
+
|
|
189
|
+
```typescript
|
|
190
|
+
// 1. Read current config
|
|
191
|
+
const current = await SL.appConfiguration.getConfig({ collectionId, appId, admin: true });
|
|
192
|
+
|
|
193
|
+
// 2. Merge the change
|
|
194
|
+
await SL.appConfiguration.setConfig({
|
|
195
|
+
collectionId,
|
|
196
|
+
appId,
|
|
197
|
+
config: { ...current, enableNotifications: true },
|
|
198
|
+
admin: true
|
|
199
|
+
});
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Metrics & Analytics
|
|
205
|
+
|
|
206
|
+
### Tracked Interactions
|
|
207
|
+
|
|
208
|
+
| Interaction ID | Description |
|
|
209
|
+
| -------------- | --------------------------------------------- |
|
|
210
|
+
| `page-view` | Tracks each time a user views the public page |
|
|
211
|
+
|
|
212
|
+
<!-- CUSTOMIZE: List all interaction IDs your app tracks. -->
|
|
213
|
+
|
|
214
|
+
### KPIs
|
|
215
|
+
|
|
216
|
+
| KPI | How to Compute |
|
|
217
|
+
| ----------- | -------------------------------------------------------------------------------------- |
|
|
218
|
+
| Total Views | `SL.interactions.countsByOutcome(collectionId, { appId, interactionId: 'page-view' })` |
|
|
219
|
+
|
|
220
|
+
<!-- CUSTOMIZE: Add app-specific KPIs and interpretation guidance. -->
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## Troubleshooting
|
|
225
|
+
|
|
226
|
+
### Common Issues
|
|
227
|
+
|
|
228
|
+
| Issue | Cause | Fix |
|
|
229
|
+
| --------------------- | -------------------------- | ----------------------------------------------------- |
|
|
230
|
+
| Config save fails | Missing `admin: true` flag | Always include `admin: true` for admin operations |
|
|
231
|
+
| Widget doesn't render | Missing required props | Ensure `collectionId`, `appId`, and `SL` are provided |
|
|
232
|
+
| Import skips rows | Invalid `productId` | Verify product IDs exist in the collection |
|
|
233
|
+
| Theme not applied | Missing `?theme=` param | Check URL parameters or postMessage setup |
|
|
234
|
+
|
|
235
|
+
<!-- CUSTOMIZE: Add app-specific troubleshooting entries. -->
|
|
236
|
+
|
|
237
|
+
### Getting Help
|
|
238
|
+
|
|
239
|
+
- **SDK Docs**: `node_modules/@proveanything/smartlinks/docs/`
|
|
240
|
+
- **App Manifest**: `public/app.manifest.json`
|
|
241
|
+
- **Platform Guide**: `src/docs/smartlinks/about.md`
|