0
# User Management
1

2
Comprehensive user identification and data management including aliases, tags, email, SMS subscriptions, and state tracking.
3

4
## Capabilities
5

6
### User State Monitoring
7

8
Monitor changes to user state including OneSignal ID and external ID changes.
9

10
```typescript { .api }
11
/**
12
 * Add a callback that fires when the OneSignal user state changes.
13
 * Important: When using the observer to retrieve the onesignalId, check the externalId 
14
 * as well to confirm the values are associated with the expected user.
15
 * @param event - Must be 'change'
16
 * @param listener - Callback function that receives user state changes
17
 */
18
function addEventListener(event: 'change', listener: (event: UserChangedState) => void): void;
19

20
/**
21
 * Clears current user state observers.  
22
 * @param event - Must be 'change'
23
 * @param listener - The callback function to remove
24
 */
25
function removeEventListener(event: 'change', listener: (event: UserChangedState) => void): void;
26
```
27

28
**Usage Example:**
29

30
```typescript
31
import { OneSignal } from "react-native-onesignal";
32

33
// Listen for user state changes
34
OneSignal.User.addEventListener('change', (event) => {
35
  console.log('User state changed:', {
36
    onesignalId: event.current.onesignalId,
37
    externalId: event.current.externalId
38
  });
39
});
40
```
41

42
### User Identification
43

44
Retrieve user identifiers for the current user session.
45

46
```typescript { .api }
47
/**
48
 * Get the nullable OneSignal Id associated with the user.
49
 * @returns Promise resolving to OneSignal user ID or null
50
 */
51
function getOnesignalId(): Promise<string | null>;
52

53
/**
54
 * Get the nullable External Id associated with the user.
55
 * @returns Promise resolving to external user ID or null  
56
 */
57
function getExternalId(): Promise<string | null>;
58
```
59

60
**Usage Example:**
61

62
```typescript
63
// Get current user IDs
64
const onesignalId = await OneSignal.User.getOnesignalId();
65
const externalId = await OneSignal.User.getExternalId();
66

67
console.log('User IDs:', { onesignalId, externalId });
68
```
69

70
### User Localization
71

72
Set the user's language for localized messaging.
73

74
```typescript { .api }
75
/**
76
 * Explicitly set a 2-character language code for the user.
77
 * @param language - ISO 639-1 two-character language code
78
 */
79
function setLanguage(language: string): void;
80
```
81

82
**Usage Example:**
83

84
```typescript
85
// Set user language for localized messages
86
OneSignal.User.setLanguage("es"); // Spanish
87
OneSignal.User.setLanguage("fr"); // French
88
```
89

90
### User Aliases
91

92
Manage user aliases for cross-platform identification and custom user mapping.
93

94
```typescript { .api }
95
/**
96
 * Set an alias for the current user. If this alias label already exists on this user, 
97
 * it will be overwritten with the new alias id.
98
 * @param label - The alias label/key
99
 * @param id - The alias value/ID
100
 */
101
function addAlias(label: string, id: string): void;
102

103
/**
104
 * Set aliases for the current user. If any alias already exists, it will be overwritten 
105
 * to the new values.
106
 * @param aliases - Object containing label-id pairs
107
 */
108
function addAliases(aliases: object): void;
109

110
/**
111
 * Remove an alias from the current user.
112
 * @param label - The alias label to remove
113
 */
114
function removeAlias(label: string): void;
115

116
/**
117
 * Remove aliases from the current user.
118
 * @param labels - Array of alias labels to remove
119
 */
120
function removeAliases(labels: string[]): void;
121
```
122

123
**Usage Examples:**
124

125
```typescript
126
// Add single alias
127
OneSignal.User.addAlias("customer_id", "12345");
128

129
// Add multiple aliases
130
OneSignal.User.addAliases({
131
  "customer_id": "12345",
132
  "loyalty_tier": "gold",
133
  "region": "us-west"
134
});
135

136
// Remove aliases
137
OneSignal.User.removeAlias("region");
138
OneSignal.User.removeAliases(["customer_id", "loyalty_tier"]);
139
```
140

141
### Email Subscriptions
142

143
Manage email subscriptions for multi-channel messaging.
144

145
```typescript { .api }
146
/**
147
 * Add a new email subscription to the current user.
148
 * @param email - Email address to add
149
 */
150
function addEmail(email: string): void;
151

152
/**
153
 * Remove an email subscription from the current user. Returns false if the specified 
154
 * email does not exist on the user within the SDK, and no request will be made.
155
 * @param email - Email address to remove
156
 */
157
function removeEmail(email: string): void;
158
```
159

160
**Usage Example:**
161

162
```typescript
163
// Add email for multi-channel messaging
164
OneSignal.User.addEmail("user@example.com");
165

166
// Remove email subscription
167
OneSignal.User.removeEmail("user@example.com");
168
```
169

170
### SMS Subscriptions
171

172
Manage SMS subscriptions for text message marketing and notifications.
173

174
```typescript { .api }
175
/**
176
 * Add a new SMS subscription to the current user.
177
 * @param smsNumber - Phone number to add
178
 */
179
function addSms(smsNumber: string): void;
180

181
/**
182
 * Remove an SMS subscription from the current user. Returns false if the specified SMS 
183
 * number does not exist on the user within the SDK, and no request will be made.
184
 * @param smsNumber - Phone number to remove
185
 */
186
function removeSms(smsNumber: string): void;
187
```
188

189
**Usage Example:**
190

191
```typescript
192
// Add SMS number for text messaging
193
OneSignal.User.addSms("+1234567890");
194

195
// Remove SMS subscription
196
OneSignal.User.removeSms("+1234567890");
197
```
198

199
### User Tags
200

201
Manage user tags for segmentation, targeting, and personalization.
202

203
```typescript { .api }
204
/**
205
 * Add a tag for the current user. Tags are key:value pairs used as building blocks for 
206
 * targeting specific users and/or personalizing messages. If the tag key already exists, 
207
 * it will be replaced with the value provided here.
208
 * @param key - Tag key
209
 * @param value - Tag value (will be converted to string if not already)
210
 */
211
function addTag(key: string, value: string): void;
212

213
/**
214
 * Add multiple tags for the current user. Tags are key:value pairs used as building blocks 
215
 * for targeting specific users and/or personalizing messages. If the tag key already exists, 
216
 * it will be replaced with the value provided here.
217
 * @param tags - Object containing key-value pairs
218
 */
219
function addTags(tags: object): void;
220

221
/**
222
 * Remove the data tag with the provided key from the current user.
223
 * @param key - Tag key to remove
224
 */
225
function removeTag(key: string): void;
226

227
/**
228
 * Remove multiple tags with the provided keys from the current user.
229
 * @param keys - Array of tag keys to remove
230
 */
231
function removeTags(keys: string[]): void;
232

233
/**
234
 * Returns the local tags for the current user.
235
 * @returns Promise resolving to object containing current user tags
236
 */
237
function getTags(): Promise<{ [key: string]: string }>;
238
```
239

240
**Usage Examples:**
241

242
```typescript
243
// Add single tag
244
OneSignal.User.addTag("subscription", "premium");
245

246
// Add multiple tags for segmentation
247
OneSignal.User.addTags({
248
  "subscription": "premium",
249
  "interests": "sports,technology",
250
  "age_group": "25-34",
251
  "location": "california"
252
});
253

254
// Get all current tags
255
const userTags = await OneSignal.User.getTags();
256
console.log("User tags:", userTags);
257

258
// Remove specific tags
259
OneSignal.User.removeTag("age_group");
260
OneSignal.User.removeTags(["interests", "location"]);
261
```