0
# Location Services
1

2
Location permission and sharing management for geo-targeted messaging capabilities.
3

4
## Capabilities
5

6
### Location Permission
7

8
Request and manage location permissions for geo-targeting features.
9

10
```typescript { .api }
11
/**
12
 * Prompts the user for location permissions to allow geotagging from the OneSignal dashboard.
13
 */
14
function requestPermission(): void;
15
```
16

17
**Usage Example:**
18

19
```typescript
20
import { OneSignal } from "react-native-onesignal";
21

22
// Request location permission for geo-targeting
23
OneSignal.Location.requestPermission();
24
```
25

26
### Location Sharing Control
27

28
Control whether location data is shared with OneSignal for geo-targeting.
29

30
```typescript { .api }
31
/**
32
 * Disable or enable location collection (defaults to enabled if your app has location permission).
33
 * @param shared - Whether to share location data with OneSignal
34
 */
35
function setShared(shared: boolean): void;
36

37
/**
38
 * Checks if location collection is enabled or disabled.
39
 * @returns Promise resolving to whether location sharing is enabled
40
 */
41
function isShared(): Promise<boolean>;
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
// Enable location sharing for geo-targeted messages
48
OneSignal.Location.setShared(true);
49

50
// Disable location sharing (privacy-focused users)
51
OneSignal.Location.setShared(false);
52

53
// Check current location sharing status
54
const isLocationShared = await OneSignal.Location.isShared();
55
console.log('Location sharing enabled:', isLocationShared);
56
```
57

58
## Complete Location Setup Flow
59

60
```typescript
61
import { OneSignal } from "react-native-onesignal";
62

63
async function setupLocationServices() {
64
  try {
65
    // Check if location is currently being shared
66
    const currentlyShared = await OneSignal.Location.isShared();
67
    console.log('Current location sharing status:', currentlyShared);
68
    
69
    if (!currentlyShared) {
70
      // Request location permission from user
71
      OneSignal.Location.requestPermission();
72
      
73
      // Enable location sharing after permission granted
74
      // Note: You may want to wait for permission callback before enabling
75
      OneSignal.Location.setShared(true);
76
      
77
      // Verify it was enabled
78
      const newStatus = await OneSignal.Location.isShared();
79
      console.log('Location sharing now enabled:', newStatus);
80
    }
81
  } catch (error) {
82
    console.error('Error setting up location services:', error);
83
  }
84
}
85

86
// Call during app initialization
87
setupLocationServices();
88
```
89

90
## Privacy Considerations
91

92
### User Control
93

94
```typescript
95
// Provide user control over location sharing
96
function handleLocationPrivacyToggle(enableLocation: boolean) {
97
  if (enableLocation) {
98
    // User opted in to location sharing
99
    OneSignal.Location.requestPermission();
100
    OneSignal.Location.setShared(true);
101
  } else {
102
    // User opted out - disable location sharing
103
    OneSignal.Location.setShared(false);
104
  }
105
}
106
```
107

108
### Conditional Location Features
109

110
```typescript
111
async function enableLocationFeaturesIfAllowed() {
112
  const isShared = await OneSignal.Location.isShared();
113
  
114
  if (isShared) {
115
    // Enable location-based features in your app
116
    console.log('Location-based notifications enabled');
117
    
118
    // You can now use geo-targeted campaigns from OneSignal dashboard
119
  } else {
120
    // Provide alternative non-location-based experience
121
    console.log('Using non-location-based targeting');
122
  }
123
}
124
```
125

126
### GDPR Compliance
127

128
```typescript
129
// For GDPR compliance, check consent before enabling location
130
function handleGDPRLocationConsent(hasConsent: boolean) {
131
  if (hasConsent) {
132
    OneSignal.Location.requestPermission();
133
    OneSignal.Location.setShared(true);
134
  } else {
135
    // Ensure location sharing is disabled
136
    OneSignal.Location.setShared(false);
137
  }
138
}
139
```
140

141
## Use Cases
142

143
### Retail Apps
144

145
```typescript
146
// Enable location for store-based promotions
147
async function setupRetailLocationFeatures() {
148
  const isShared = await OneSignal.Location.isShared();
149
  
150
  if (!isShared) {
151
    // Explain benefits to user
152
    showLocationBenefitsModal({
153
      onAccept: () => {
154
        OneSignal.Location.requestPermission();
155
        OneSignal.Location.setShared(true);
156
      },
157
      onDecline: () => {
158
        OneSignal.Location.setShared(false);
159
      }
160
    });
161
  }
162
}
163
```
164

165
### Event Apps
166

167
```typescript
168
// Location for event-based notifications
169
async function setupEventLocationTracking() {
170
  // Request location for event proximity notifications
171
  OneSignal.Location.requestPermission();
172
  OneSignal.Location.setShared(true);
173
  
174
  console.log('Event location tracking enabled');
175
  // Users will now receive notifications based on proximity to event venues
176
}
177
```
178

179
### Delivery Apps
180

181
```typescript
182
// Essential location tracking for delivery apps
183
async function setupDeliveryLocationTracking() {
184
  // Location is critical for delivery apps
185
  OneSignal.Location.requestPermission();
186
  OneSignal.Location.setShared(true);
187
  
188
  const isEnabled = await OneSignal.Location.isShared();
189
  if (!isEnabled) {
190
    // Show critical location requirement dialog
191
    showLocationRequiredDialog();
192
  }
193
}
194
```
195

196
### Weather Apps
197

198
```typescript
199
// Location for weather-based alerts
200
async function setupWeatherLocationServices() {
201
  OneSignal.Location.requestPermission();
202
  OneSignal.Location.setShared(true);
203
  
204
  // Users will receive weather alerts based on their location
205
  console.log('Weather location services enabled');
206
}
207
```
208

209
## Platform Behavior
210

211
### iOS
212
- Requests standard iOS location permission dialog
213
- Respects user's location privacy settings
214
- Integrates with iOS location services
215

216
### Android  
217
- Requests Android location permissions
218
- Handles runtime permission requests
219
- Respects Android location settings
220

221
```typescript
222
import { Platform } from 'react-native';
223

224
function platformSpecificLocationSetup() {
225
  if (Platform.OS === 'ios') {
226
    // iOS-specific location setup if needed
227
    OneSignal.Location.requestPermission();
228
  } else if (Platform.OS === 'android') {
229
    // Android-specific location setup if needed  
230
    OneSignal.Location.requestPermission();
231
  }
232
  
233
  // Common location sharing setup
234
  OneSignal.Location.setShared(true);
235
}
236
```