OMX Logo
Documentation
Management

Manage Geotriggers

Learn how to update, delete, and monitor your geotriggers with comprehensive management tools and analytics.

Geotrigger Management

Once your geotriggers are created, you need comprehensive tools to manage, monitor, and optimize their performance. This guide covers all aspects of geotrigger lifecycle management.

List and Search Geotriggers

Retrieve and filter your geotriggers with advanced search capabilities:

import { OMXClient } from '@omx-sdk/geotrigger';

const omx = new OMXClient({
  clientId: 'your_client_id',
  secretKey: 'your_secret_key'
});

// List all geotriggers
const triggers = await omx.geotrigger.list();
console.log(triggers);

// Search with filters
const filteredTriggers = await omx.geotrigger.list({
  status: 'active',
  type: 'circular',
  tags: ['retail', 'promotion'],
  createdAfter: '2024-01-01',
  limit: 50,
  offset: 0
});

// Search by location proximity
const nearbyTriggers = await omx.geotrigger.searchByLocation({
  lat: 40.7128,
  lng: -74.0060,
  radius: 5000, // 5km
  limit: 20
});

// Search by name or description
const searchResults = await omx.geotrigger.search({
  query: 'coffee shop promotion',
  fuzzy: true,
  limit: 10
});

Update Geotriggers

Modify existing geotriggers with partial or complete updates:

// Partial update
const updatedTrigger = await omx.geotrigger.update('trigger_123', {
  name: 'Updated Coffee Shop Promotion',
  description: 'Extended promotion with new offers',
  isActive: true
});

// Update geometry
await omx.geotrigger.updateGeometry('trigger_123', {
  type: 'circular',
  center: { lat: 40.7580, lng: -73.9855 },
  radius: 150
});

// Update targeting criteria
await omx.geotrigger.updateTargeting('trigger_123', {
  userSegments: ['premium_customers', 'local_residents'],
  deviceTypes: ['ios', 'android'],
  timeRestrictions: {
    daysOfWeek: [1, 2, 3, 4, 5], // Monday to Friday
    startTime: '09:00',
    endTime: '18:00',
    timezone: 'America/New_York'
  }
});

// Bulk update
const bulkUpdates = await omx.geotrigger.bulkUpdate([
  { id: 'trigger_123', data: { isActive: false } },
  { id: 'trigger_456', data: { priority: 'high' } },
  { id: 'trigger_789', data: { tags: ['seasonal', 'holiday'] } }
]);

Status Management

Control geotrigger activation and lifecycle states:

// Activate/Deactivate triggers
await omx.geotrigger.activate('trigger_123');
await omx.geotrigger.deactivate('trigger_456');

// Pause temporarily
await omx.geotrigger.pause('trigger_789', {
  reason: 'Maintenance window',
  resumeAt: '2024-02-01T10:00:00Z'
});

// Resume paused trigger
await omx.geotrigger.resume('trigger_789');

// Check status
const status = await omx.geotrigger.getStatus('trigger_123');
console.log(status);
// {
//   id: 'trigger_123',
//   status: 'active',
//   lastTriggered: '2024-01-15T14:30:00Z',
//   totalTriggers: 47,
//   isHealthy: true
// }

// Bulk status operations
await omx.geotrigger.bulkActivate(['trigger_123', 'trigger_456']);
await omx.geotrigger.bulkDeactivate(['trigger_789', 'trigger_101']);

Performance Analytics

Monitor geotrigger performance and user interactions:

// Get detailed analytics
const analytics = await omx.geotrigger.getAnalytics('trigger_123', {
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  granularity: 'daily' // 'hourly', 'daily', 'weekly', 'monthly'
});

console.log(analytics);
// {
//   triggerId: 'trigger_123',
//   period: { start: '2024-01-01', end: '2024-01-31' },
//   metrics: {
//     totalTriggers: 234,
//     uniqueUsers: 156,
//     averageEngagementTime: 45.2,
//     conversionRate: 0.23,
//     clickThroughRate: 0.67
//   },
//   timeline: [
//     { date: '2024-01-01', triggers: 8, users: 6 },
//     { date: '2024-01-02', triggers: 12, users: 9 }
//   ]
// }

// Performance comparison
const comparison = await omx.geotrigger.comparePerformance([
  'trigger_123',
  'trigger_456',
  'trigger_789'
], {
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  metrics: ['triggers', 'engagement', 'conversion']
});

// Heat map data
const heatMap = await omx.geotrigger.getHeatMap('trigger_123', {
  resolution: 'high', // 'low', 'medium', 'high'
  timeRange: '7d'
});

Health Monitoring

Monitor geotrigger health and detect issues:

// Health check for individual trigger
const health = await omx.geotrigger.checkHealth('trigger_123');
console.log(health);
// {
//   id: 'trigger_123',
//   status: 'healthy',
//   issues: [],
//   recommendations: [],
//   lastChecked: '2024-01-15T10:30:00Z',
//   metrics: {
//     uptime: 99.8,
//     responseTime: 120,
//     errorRate: 0.01
//   }
// }

// Health check for all triggers
const healthReport = await omx.geotrigger.getHealthReport();
console.log(healthReport);
// {
//   overall: 'good',
//   healthy: 45,
//   warning: 3,
//   critical: 1,
//   inactive: 5,
//   issues: [
//     {
//       triggerId: 'trigger_456',
//       severity: 'warning',
//       issue: 'Low engagement rate',
//       recommendation: 'Consider adjusting targeting criteria'
//     }
//   ]
// }

// Set up health monitoring alerts
await omx.geotrigger.setupHealthAlerts({
  triggers: ['trigger_123', 'trigger_456'],
  conditions: {
    errorRate: { threshold: 0.05, operator: 'greater_than' },
    responseTime: { threshold: 1000, operator: 'greater_than' },
    engagementRate: { threshold: 0.1, operator: 'less_than' }
  },
  actions: [
    { type: 'email', recipient: 'admin@yourapp.com' },
    { type: 'webhook', url: 'https://yourapp.com/alerts' }
  ]
});

User Interaction Logs

Access detailed logs of user interactions with your geotriggers:

// Get interaction logs
const logs = await omx.geotrigger.getLogs('trigger_123', {
  startDate: '2024-01-15',
  endDate: '2024-01-16',
  eventTypes: ['enter', 'exit', 'dwell'],
  limit: 100
});

console.log(logs);
// [
//   {
//     id: 'log_789',
//     triggerId: 'trigger_123',
//     userId: 'user_456',
//     eventType: 'enter',
//     timestamp: '2024-01-15T14:30:15Z',
//     location: { lat: 40.7128, lng: -74.0060 },
//     device: { type: 'ios', version: '17.0' },
//     metadata: { accuracy: 5, speed: 0 }
//   }
// ]

// Export logs for analysis
const exportUrl = await omx.geotrigger.exportLogs('trigger_123', {
  format: 'csv',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  includeMetadata: true
});

// Real-time log streaming
const logStream = omx.geotrigger.streamLogs('trigger_123');
logStream.on('log', (log) => {
  console.log('New interaction:', log);
});

// Filter logs by user segment
const segmentLogs = await omx.geotrigger.getLogsBySegment('trigger_123', {
  segment: 'premium_customers',
  startDate: '2024-01-01',
  groupBy: 'day'
});

Optimization Tools

Use built-in tools to optimize geotrigger performance:

// Get optimization recommendations
const recommendations = await omx.geotrigger.getOptimizationRecommendations('trigger_123');
console.log(recommendations);
// [
//   {
//     type: 'geometry',
//     priority: 'high',
//     recommendation: 'Reduce radius from 200m to 150m',
//     reason: 'Current radius causes too many false positives',
//     expectedImprovement: { accuracy: '+15%', engagement: '+8%' }
//   },
//   {
//     type: 'targeting',
//     priority: 'medium',
//     recommendation: 'Add time restrictions for business hours',
//     reason: 'Low engagement during non-business hours',
//     expectedImprovement: { efficiency: '+12%' }
//   }
// ]

// Apply recommended optimizations
await omx.geotrigger.applyOptimization('trigger_123', {
  optimizationId: 'opt_123',
  autoApprove: false
});

// A/B test different configurations
const abTest = await omx.geotrigger.createABTest({
  name: 'Radius Optimization Test',
  triggerId: 'trigger_123',
  variants: [
    { name: 'Control', config: { radius: 200 } },
    { name: 'Smaller Radius', config: { radius: 150 } },
    { name: 'Larger Radius', config: { radius: 250 } }
  ],
  trafficSplit: [40, 30, 30], // Percentage for each variant
  duration: '7d',
  metrics: ['engagement_rate', 'conversion_rate']
});

// Monitor A/B test results
const testResults = await omx.geotrigger.getABTestResults(abTest.id);

Backup and Recovery

Backup your geotrigger configurations and restore when needed:

// Create backup
const backup = await omx.geotrigger.createBackup({
  triggerIds: ['trigger_123', 'trigger_456'],
  includeAnalytics: true,
  compression: 'gzip'
});

// List available backups
const backups = await omx.geotrigger.listBackups();

// Restore from backup
await omx.geotrigger.restore({
  backupId: backup.id,
  options: {
    overwriteExisting: false,
    preserveIds: true,
    restoreAnalytics: false
  }
});

// Schedule automatic backups
await omx.geotrigger.scheduleBackup({
  frequency: 'daily',
  time: '02:00',
  timezone: 'UTC',
  retention: '30d',
  includeAll: true
});

Delete and Cleanup

Safely delete geotriggers and clean up associated data:

// Soft delete (can be restored)
await omx.geotrigger.delete('trigger_123', { soft: true });

// Hard delete (permanent)
await omx.geotrigger.delete('trigger_456', { 
  soft: false,
  deleteAnalytics: true,
  deleteLogs: true
});

// Bulk delete
await omx.geotrigger.bulkDelete(['trigger_789', 'trigger_101'], {
  soft: true
});

// Restore soft-deleted trigger
await omx.geotrigger.restore('trigger_123');

// Clean up inactive triggers
const cleanupResult = await omx.geotrigger.cleanup({
  inactiveDays: 30,
  zeroEngagementDays: 14,
  dryRun: true // Set to false to actually delete
});

console.log(`Would delete ${cleanupResult.candidateCount} triggers`);

Best Practices

  • Regular Monitoring: Set up health alerts and review analytics weekly
  • Performance Optimization: Apply recommendations and run A/B tests
  • Data Retention: Establish clear policies for log and analytics retention
  • Backup Strategy: Schedule regular backups before major changes
  • Cleanup Routine: Regularly remove unused or underperforming triggers
  • Documentation: Maintain clear naming and tagging conventions

Next Steps