0
# Push Subscription Management
1

2
Push notification subscription handling including permission status, subscription state, and opt-in/opt-out controls.
3

4
## Capabilities
5

6
### Subscription State Monitoring
7

8
Monitor changes to push subscription state including subscription ID, token, and opt-in status.
9

10
```typescript { .api }
11
/**
12
 * Add a callback that fires when the OneSignal subscription state changes.
13
 * @param event - Must be 'change'
14
 * @param listener - Callback function that receives subscription state changes
15
 */
16
function addEventListener(event: 'change', listener: (event: PushSubscriptionChangedState) => void): void;
17

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

26
**Usage Example:**
27

28
```typescript
29
import { OneSignal } from "react-native-onesignal";
30

31
// Listen for subscription changes
32
OneSignal.User.pushSubscription.addEventListener('change', (event) => {
33
  console.log('Subscription changed:', {
34
    previous: {
35
      id: event.previous.id,
36
      token: event.previous.token,
37
      optedIn: event.previous.optedIn
38
    },
39
    current: {
40
      id: event.current.id,
41
      token: event.current.token, 
42
      optedIn: event.current.optedIn
43
    }
44
  });
45
});
46
```
47

48
### Subscription Identification
49

50
Retrieve subscription identifiers and tokens for the current device.
51

52
```typescript { .api }
53
/**
54
 * Get the push subscription ID asynchronously.
55
 * @returns Promise resolving to subscription ID or null
56
 */
57
function getIdAsync(): Promise<string | null>;
58

59
/**
60
 * The readonly push subscription token.
61
 * @returns Promise resolving to subscription token or null
62
 */
63
function getTokenAsync(): Promise<string | null>;
64
```
65

66
**Usage Example:**
67

68
```typescript
69
// Get current subscription details
70
const subscriptionId = await OneSignal.User.pushSubscription.getIdAsync();
71
const subscriptionToken = await OneSignal.User.pushSubscription.getTokenAsync();
72

73
console.log('Subscription details:', {
74
  id: subscriptionId,
75
  token: subscriptionToken
76
});
77
```
78

79
### Subscription Status
80

81
Check and manage the user's opt-in status for push notifications.
82

83
```typescript { .api }
84
/**
85
 * Gets a boolean value indicating whether the current user is opted in to push notifications.
86
 * This returns true when the app has notifications permission and optOut is not called.
87
 * Note: Does not take into account the existence of the subscription ID and push token.
88
 * This boolean may return true but push notifications may still not be received by the user.
89
 * @returns Promise resolving to opt-in status
90
 */
91
function getOptedInAsync(): Promise<boolean>;
92
```
93

94
**Usage Example:**
95

96
```typescript
97
// Check if user is opted in to push notifications
98
const isOptedIn = await OneSignal.User.pushSubscription.getOptedInAsync();
99
console.log('User opted in to push:', isOptedIn);
100
```
101

102
### Subscription Control
103

104
Control the user's push notification subscription status.
105

106
```typescript { .api }
107
/**
108
 * Disable the push notification subscription to OneSignal.
109
 */
110
function optOut(): void;
111

112
/**
113
 * Enable the push notification subscription to OneSignal.
114
 */
115
function optIn(): void;
116
```
117

118
**Usage Examples:**
119

120
```typescript
121
// User opts out of push notifications
122
OneSignal.User.pushSubscription.optOut();
123

124
// User opts back in to push notifications  
125
OneSignal.User.pushSubscription.optIn();
126

127
// Check status after change
128
const newStatus = await OneSignal.User.pushSubscription.getOptedInAsync();
129
console.log('New opt-in status:', newStatus);
130
```
131

132
### Deprecated Methods
133

134
The following methods are deprecated but still available for backward compatibility:
135

136
```typescript { .api }
137
/**
138
 * @deprecated This method is deprecated. It has been replaced by getIdAsync.
139
 */
140
function getPushSubscriptionId(): string;
141

142
/**
143
 * @deprecated This method is deprecated. It has been replaced by getTokenAsync.
144
 */
145
function getPushSubscriptionToken(): string;
146

147
/**
148
 * @deprecated This method is deprecated. It has been replaced by getOptedInAsync.
149
 */
150
function getOptedIn(): boolean;
151
```
152

153
**Migration Example:**
154

155
```typescript
156
// OLD (deprecated) - synchronous methods
157
const oldId = OneSignal.User.pushSubscription.getPushSubscriptionId();
158
const oldToken = OneSignal.User.pushSubscription.getPushSubscriptionToken();
159
const oldOptedIn = OneSignal.User.pushSubscription.getOptedIn();
160

161
// NEW - async methods with better error handling
162
const newId = await OneSignal.User.pushSubscription.getIdAsync();
163
const newToken = await OneSignal.User.pushSubscription.getTokenAsync();
164
const newOptedIn = await OneSignal.User.pushSubscription.getOptedInAsync();
165
```
166

167
## Types
168

169
```typescript { .api }
170
interface PushSubscriptionState {
171
  id?: string;
172
  token?: string;
173
  optedIn: boolean;
174
}
175

176
interface PushSubscriptionChangedState {
177
  previous: PushSubscriptionState;
178
  current: PushSubscriptionState;
179
}
180
```