0
# In-App Messages
1

2
Trigger-based in-app messaging system with lifecycle event handling and display control.
3

4
## Capabilities
5

6
### In-App Message Event Handling
7

8
Handle in-app message clicks and lifecycle events including display and dismiss events.
9

10
```typescript { .api }
11
/**
12
 * Add listeners for In-App Message click and/or lifecycle events.
13
 * @param event - The event type to listen for
14
 * @param listener - Callback function for the event
15
 */
16
function addEventListener<K extends InAppMessageEventName>(
17
  event: K,
18
  listener: (event: InAppMessageEventTypeMap[K]) => void
19
): void;
20

21
/**
22
 * Remove listeners for In-App Message click and/or lifecycle events.
23
 * @param event - The event type to stop listening for
24
 * @param listener - The callback function to remove
25
 */
26
function removeEventListener<K extends InAppMessageEventName>(
27
  event: K,
28
  listener: (obj: InAppMessageEventTypeMap[K]) => void
29
): void;
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { OneSignal } from "react-native-onesignal";
36

37
// Handle in-app message clicks
38
OneSignal.InAppMessages.addEventListener('click', (event) => {
39
  console.log('In-app message clicked:', {
40
    messageId: event.message.messageId,
41
    actionId: event.result.actionId,
42
    url: event.result.url,
43
    closingMessage: event.result.closingMessage
44
  });
45
  
46
  // Handle click actions
47
  if (event.result.url) {
48
    // Open URL or navigate
49
  }
50
});
51

52
// Handle message lifecycle events
53
OneSignal.InAppMessages.addEventListener('willDisplay', (event) => {
54
  console.log('In-app message will display:', event.message.messageId);
55
});
56

57
OneSignal.InAppMessages.addEventListener('didDisplay', (event) => {
58
  console.log('In-app message displayed:', event.message.messageId);
59
});
60

61
OneSignal.InAppMessages.addEventListener('willDismiss', (event) => {
62
  console.log('In-app message will dismiss:', event.message.messageId);
63
});
64

65
OneSignal.InAppMessages.addEventListener('didDismiss', (event) => {
66
  console.log('In-app message dismissed:', event.message.messageId);
67
});
68
```
69

70
### Trigger Management
71

72
Manage triggers that determine when in-app messages should be displayed to users.
73

74
```typescript { .api }
75
/**
76
 * Add a trigger for the current user. Triggers are currently explicitly used to determine 
77
 * whether a specific IAM should be displayed to the user.
78
 * @param key - Trigger key
79
 * @param value - Trigger value
80
 */
81
function addTrigger(key: string, value: string): void;
82

83
/**
84
 * Add multiple triggers for the current user. Triggers are currently explicitly used to 
85
 * determine whether a specific IAM should be displayed to the user.
86
 * @param triggers - Object containing key-value trigger pairs
87
 */
88
function addTriggers(triggers: { [key: string]: string }): void;
89

90
/**
91
 * Remove the trigger with the provided key from the current user.
92
 * @param key - Trigger key to remove
93
 */
94
function removeTrigger(key: string): void;
95

96
/**
97
 * Remove multiple triggers from the current user.
98
 * @param keys - Array of trigger keys to remove
99
 */
100
function removeTriggers(keys: string[]): void;
101

102
/**
103
 * Clear all triggers from the current user.
104
 */
105
function clearTriggers(): void;
106
```
107

108
**Usage Examples:**
109

110
```typescript
111
// Add single trigger to show welcome message
112
OneSignal.InAppMessages.addTrigger("page", "home");
113

114
// Add multiple triggers for targeting
115
OneSignal.InAppMessages.addTriggers({
116
  "level": "5",
117
  "stage": "tutorial_complete", 
118
  "subscription": "premium",
119
  "session_count": "3"
120
});
121

122
// Remove specific trigger
123
OneSignal.InAppMessages.removeTrigger("level");
124

125
// Remove multiple triggers
126
OneSignal.InAppMessages.removeTriggers(["stage", "session_count"]);
127

128
// Clear all triggers (useful for logout)
129
OneSignal.InAppMessages.clearTriggers();
130
```
131

132
### Message Display Control
133

134
Control whether in-app messages are displayed to the user.
135

136
```typescript { .api }
137
/**
138
 * Set whether in-app messaging is currently paused.
139
 * When set to true no IAM will be presented to the user regardless of whether they qualify for them.
140
 * When set to false any IAMs the user qualifies for will be presented to the user at the appropriate time.
141
 * @param pause - Whether to pause in-app messages
142
 */
143
function setPaused(pause: boolean): void;
144

145
/**
146
 * Whether in-app messaging is currently paused.
147
 * @returns Promise resolving to paused status
148
 */
149
function getPaused(): Promise<boolean>;
150
```
151

152
**Usage Examples:**
153

154
```typescript
155
// Pause in-app messages during onboarding
156
OneSignal.InAppMessages.setPaused(true);
157

158
// Resume in-app messages after onboarding
159
OneSignal.InAppMessages.setPaused(false);
160

161
// Check current paused status
162
const isPaused = await OneSignal.InAppMessages.getPaused();
163
console.log('In-app messages paused:', isPaused);
164

165
// Conditionally pause based on app state
166
if (isInCriticalFlow) {
167
  OneSignal.InAppMessages.setPaused(true);
168
}
169
```
170

171
## Common Use Cases
172

173
### Welcome Flow Triggers
174

175
```typescript
176
// Set triggers to show welcome messages based on user progress
177
OneSignal.InAppMessages.addTriggers({
178
  "welcome_step": "1",
179
  "first_session": "true"
180
});
181

182
// Update trigger as user progresses
183
OneSignal.InAppMessages.addTrigger("welcome_step", "2");
184

185
// Clear welcome triggers when complete
186
OneSignal.InAppMessages.removeTriggers(["welcome_step", "first_session"]);
187
```
188

189
### Feature Announcement Targeting
190

191
```typescript
192
// Target users who haven't seen new feature
193
OneSignal.InAppMessages.addTriggers({
194
  "app_version": "2.1.0",
195
  "feature_announcement_seen": "false",
196
  "user_level": "advanced" 
197
});
198

199
// Mark as seen after display
200
OneSignal.InAppMessages.addEventListener('didDisplay', (event) => {
201
  if (event.message.messageId === 'feature-announcement-id') {
202
    OneSignal.InAppMessages.addTrigger("feature_announcement_seen", "true");
203
  }
204
});
205
```
206

207
### Contextual Messaging
208

209
```typescript
210
// Set triggers based on current screen/context
211
OneSignal.InAppMessages.addTriggers({
212
  "current_screen": "checkout",
213
  "cart_value": "high",
214
  "first_time_buyer": "true"
215
});
216

217
// Update context as user navigates
218
function onScreenChange(screenName) {
219
  OneSignal.InAppMessages.addTrigger("current_screen", screenName);
220
}
221
```
222

223
## Types
224

225
```typescript { .api }
226
type InAppMessageEventName = 'click' | 'willDisplay' | 'didDisplay' | 'willDismiss' | 'didDismiss';
227

228
type InAppMessageEventTypeMap = {
229
  click: InAppMessageClickEvent;
230
  willDisplay: InAppMessageWillDisplayEvent;
231
  didDisplay: InAppMessageDidDisplayEvent;
232
  willDismiss: InAppMessageWillDismissEvent;
233
  didDismiss: InAppMessageDidDismissEvent;
234
};
235

236
interface InAppMessage {
237
  messageId: string;
238
}
239

240
interface InAppMessageClickEvent {
241
  message: InAppMessage;
242
  result: InAppMessageClickResult;
243
}
244

245
interface InAppMessageClickResult {
246
  closingMessage: boolean;
247
  actionId?: string;
248
  url?: string;
249
  urlTarget?: string;
250
}
251

252
interface InAppMessageWillDisplayEvent {
253
  message: InAppMessage;
254
}
255

256
interface InAppMessageDidDisplayEvent {
257
  message: InAppMessage;
258
}
259

260
interface InAppMessageWillDismissEvent {
261
  message: InAppMessage;
262
}
263

264
interface InAppMessageDidDismissEvent {
265
  message: InAppMessage;
266
}
267
```