Geotrigger
Geotrigger Getting Started
Learn how to create location-based triggers with the OMX Geotrigger API.
Geotrigger Getting Started
Build with confidence
Geotriggers allow you to create location-based automation by defining virtual boundaries (geofences) that trigger actions when users enter, exit, or dwell within specific areas.
Quick Start
Get location-based triggers running in minutes with these simple steps.
1
Install Dependencies
First, make sure you have the Core SDK installed, then add the Geotrigger module:
typescript
1npm install @omx-sdk/core @omx-sdk/geotrigger
2
Initialize the SDK
Set up the Geotrigger module with your OMX client:
typescript
1import { OMXClient } from '@omx-sdk/core';
2import { GeoTrigger } from '@omx-sdk/geotrigger';
3
4const omx = new OMXClient({
5 clientId: 'your_client_id',
6 secretKey: 'your_secret_key'
7});
8
9const geoTrigger = new GeoTrigger(omx);
Core Capabilities
Powerful location-based features to enhance your application.
Location-based Triggers
Create virtual boundaries that respond to user location changes in real-time.
Geofencing
Define circular or polygon-shaped geographic areas with precision.
Real-time Processing
Instant notifications and actions when location events occur.
Custom Shapes
Create complex polygon geofences to match any geographic area.
Privacy Compliance
Always obtain user consent before tracking location data and comply with local privacy regulations like GDPR and CCPA.
Creating Your First Geotrigger
Create a simple geotrigger that sends a notification when users enter a specific location.
typescript
1const trigger = await geoTrigger.create({
2 name: "Coffee Shop Welcome",
3 description: "Welcome customers to our coffee shop",
4
5 // Define the geographic area
6 location: {
7 latitude: 40.7128,
8 longitude: -74.0060,
9 radius: 100 // meters
10 },
11
12 // Define what happens when someone enters
13 onEnter: {
14 notification: {
15 title: "Welcome to Joe's Coffee!",
16 body: "Get 20% off your first order with code WELCOME20",
17 data: {
18 couponCode: "WELCOME20",
19 discount: 0.20
20 }
21 }
22 },
23
24 // Optional: what happens when someone exits
25 onExit: {
26 webhook: {
27 url: "https://your-app.com/webhooks/geotrigger-exit",
28 method: "POST"
29 }
30 },
31
32 // Trigger settings
33 settings: {
34 enabled: true,
35 maxTriggersPerUser: 1, // Only trigger once per user
36 cooldownPeriod: 3600 // 1 hour cooldown between triggers
37 }
38});
39
40console.log('Geotrigger created:', trigger.id);
Geotrigger Types
Different types of geofences to match your use case.
Circular Geofences
The most common type, defined by a center point and radius. Perfect for most location-based scenarios.
Polygon Geofences
For complex shapes, define multiple coordinates to create custom geographic boundaries.
Circular Geofence
The most common type, defined by a center point and radius.
typescript
1location: {
2 latitude: 40.7128,
3 longitude: -74.0060,
4 radius: 100 // meters
5}
Polygon Geofence
For more complex shapes, define multiple coordinates.
typescript
1location: {
2 type: "polygon",
3 coordinates: [
4 [40.7128, -74.0060],
5 [40.7130, -74.0058],
6 [40.7132, -74.0062],
7 [40.7128, -74.0060] // Close the polygon
8 ]
9}
Event Types
Different types of location events you can respond to.
Enter Events
Triggered when a user enters the geofenced area.
Exit Events
Triggered when a user leaves the geofenced area.
Dwell Events
Triggered when a user stays in the area for a specific duration.
Enter Events
Triggered when a user enters the geofenced area.
typescript
1onEnter: {
2 notification: { /* push notification */ },
3 email: { /* email action */ },
4 webhook: { /* webhook call */ },
5 customAction: { /* custom logic */ }
6}
Exit Events
Triggered when a user leaves the geofenced area.
typescript
1onExit: {
2 webhook: {
3 url: "https://your-app.com/user-left",
4 headers: {
5 "Authorization": "Bearer your-token"
6 }
7 }
8}
Dwell Events
Triggered when a user stays in the area for a specific duration.
typescript
1onDwell: {
2 minimumDuration: 300, // 5 minutes in seconds
3 notification: {
4 title: "Still here?",
5 body: "Enjoy a free coffee on us!"
6 }
7}
Advanced Targeting Options
Control which users are affected by your geotriggers with sophisticated targeting rules.
typescript
1targeting: {
2 // Target specific users
3 userIds: ["user1", "user2"],
4
5 // Target user segments
6 segments: ["premium-customers", "local-users"],
7
8 // Target by user properties
9 userProperties: {
10 age: { min: 18, max: 65 },
11 hasAppInstalled: true
12 },
13
14 // Time-based targeting
15 schedule: {
16 startDate: "2024-01-01",
17 endDate: "2024-12-31",
18 timeZone: "America/New_York",
19 hours: [9, 10, 11, 16, 17, 18] // Business hours
20 }
21}
Managing Geotriggers
Full lifecycle management for your location-based triggers.
List & Filter
Retrieve and filter geotriggers by status, location, or other criteria.
Update & Configure
Modify geotrigger settings, locations, and actions dynamically.
List Geotriggers
Retrieve all geotriggers with pagination.
typescript
1const triggers = await geoTrigger.list({
2 page: 1,
3 limit: 10,
4 status: 'active'
5});
Update Geotrigger
Modify existing geotrigger settings.
typescript
1await geoTrigger.update('trigger-id', {
2 name: "Updated Coffee Shop Welcome",
3 settings: {
4 enabled: false
5 }
6});
Delete Geotrigger
Remove a geotrigger from your system.
typescript
1await geoTrigger.delete('trigger-id');
Best Practices
- Reasonable Radius: Use 50-200 meter radius for most use cases
- Cooldown Periods: Prevent spam by setting appropriate cooldowns
- Battery Optimization: Limit the number of active geotriggers per user
- Relevant Content: Ensure notifications are contextually relevant
- Privacy Compliance: Always get user consent for location tracking
- Testing: Test geotriggers thoroughly before deploying to production
Next Steps
Continue your journey with advanced geotrigger features and guides.