Offline Functionality

The ContactsManager SDK stores contact data locally on your device, enabling basic offline functionality. This guide explains how contacts are managed in offline scenarios and how synchronization works.

Offline-First Approach

The SDK stores all contact data locally on the device using SwiftData, which means:

All contact data is accessible offline through the local database
Contacts can be viewed and queried even without an internet connection
Changes made while offline are synchronized when connectivity is restored

Working with Contacts Offline

Fetching Contacts

You can fetch contacts from the local database at any time, regardless of connection status:

do {
    // Fetch contacts from local storage
    let contacts = try await ContactsService.shared.fetchContacts()
    print("Retrieved \(contacts.count) contacts from local storage")
} catch {
    print("Error fetching contacts: \(error.localizedDescription)")
}

import { fetchContacts } from '@contactsmanager/rn';

try {
  // Fetch contacts from local storage
  const contacts = await fetchContacts();
  console.log(`Retrieved ${contacts.length} contacts from local storage`);
} catch (error) {
  console.error('Error fetching contacts:', error);
}

// Coming Soon

// Coming Soon

You can also fetch contacts with specific field types:

do {
    // Fetch only contacts with phone numbers
    let contactsWithPhones = try await ContactsService.shared.fetchContacts(
        fieldType: .phone
    )
    print("Found \(contactsWithPhones.count) contacts with phone numbers")
} catch {
    print("Error fetching contacts: \(error.localizedDescription)")
}

import { fetchContacts, ContactFieldType } from '@contactsmanager/rn';

try {
  // Fetch only contacts with phone numbers
  const contactsWithPhones = await fetchContacts(ContactFieldType.Phone);
  console.log(`Found ${contactsWithPhones.length} contacts with phone numbers`);
} catch (error) {
  console.error('Error fetching contacts:', error);
}

// Coming Soon

// Coming Soon

Fetching a Single Contact

To retrieve a specific contact:

do {
    // Fetch a contact from local storage
    if let contact = try await ContactsService.shared.fetchContact(withId: contactId) {
        print("Found contact: \(contact.displayName ?? "Unknown")")
    } else {
        print("Contact not found")
    }
} catch {
    print("Error fetching contact: \(error.localizedDescription)")
}

import { fetchContact } from '@contactsmanager/rn';

try {
  // Fetch a contact from local storage
  const contact = await fetchContact(contactId);
  
  if (contact) {
    console.log(`Found contact: ${contact.displayName || 'Unknown'}`);
  } else {
    console.log('Contact not found');
  }
} catch (error) {
  console.error('Error fetching contact:', error);
}

// Coming Soon

// Coming Soon

Synchronization Management

Manual Synchronization

The SDK automatically attempts to synchronize contacts when the app becomes active, when the contact store changes, or when contacts access is granted. You can also trigger manual synchronization:

do {
    // Force a sync with the server
    let syncedCount = try await ContactsService.shared.syncContacts()
    print("Synchronized \(syncedCount) contacts successfully")
} catch {
    print("Synchronization error: \(error.localizedDescription)")
}

import { syncContacts } from '@contactsmanager/rn';

try {
  // Force a sync with the server
  const syncedCount = await syncContacts();
  console.log(`Synchronized ${syncedCount} contacts successfully`);
} catch (error) {
  console.error('Synchronization error:', error);
}

// Coming Soon

// Coming Soon

Background Synchronization

You can enable background synchronization by calling the following method during app initialization (typically in your AppDelegate or App):

// Enable background synchronization capabilities
ContactsService.shared.enableBackgroundSync()

import { enableBackgroundSync } from '@contactsmanager/rn';

// In your app initialization (e.g., App.js or index.js)
enableBackgroundSync();

// Coming Soon

// Coming Soon

This registers a background task with the system that will periodically synchronize contacts even when your app is in the background. Social features rely more heavily on server connectivity, but some operations are queued for later synchronization when offline.

Following Contacts

To follow a contact (will be synchronized when online):

do {
    let result = try await ContactsService.shared.socialService.followContact(
        followedId: contactId,
        contactId: contactId
    )
    
    if let success = result.success, success {
        print("Follow request processed")
    } else if let alreadyFollowing = result.alreadyFollowing, alreadyFollowing {
        print("Already following this contact")
    }
} catch {
    print("Error processing follow request: \(error.localizedDescription)")
}

import { followContact } from '@contactsmanager/rn';

try {
  const result = await followContact(contactId, contactId);
  
  if (result.success) {
    console.log('Follow request processed');
  } else if (result.alreadyFollowing) {
    console.log('Already following this contact');
  }
} catch (error) {
  console.error('Error processing follow request:', error);
}

// Coming Soon

// Coming Soon

While contact data is fully accessible offline, social features have some limitations:

New user discovery: Finding new users requires connectivity
Activity feeds: New remote events can’t be fetched while offline
Follow status: New follow relationships from other users won’t be visible until synchronization

Implementing an Offline-Aware UI

To provide a good user experience, your UI should be aware of potential synchronization states. Here’s a simplified example:

struct ContactListView: View {
    @State private var contacts: [Contact] = []
    @State private var isLoading = false
    
    var body: some View {
        NavigationView {
            VStack {
                if isLoading {
                    ProgressView("Loading contacts...")
                } else {
                    List(contacts, id: \.id) { contact in
                        ContactRow(contact: contact)
                    }
                    .listStyle(PlainListStyle())
                }
            }
            .navigationTitle("Contacts")
            .onAppear {
                loadContacts()
            }
            .refreshable {
                await syncContacts()
            }
        }
    }
    
    private func loadContacts() {
        isLoading = true
        Task {
            do {
                let fetchedContacts = try await ContactsService.shared.fetchContacts()
                
                await MainActor.run {
                    self.contacts = fetchedContacts
                    self.isLoading = false
                }
            } catch {
                print("Error loading contacts: \(error.localizedDescription)")
                await MainActor.run {
                    self.isLoading = false
                }
            }
        }
    }
    
    private func syncContacts() async {
        do {
            try await ContactsService.shared.syncContacts()
            // Reload contacts after sync
            loadContacts()
        } catch {
            print("Error syncing contacts: \(error.localizedDescription)")
        }
    }
}

import React, { useState, useEffect } from 'react';
import {
  View,
  Text,
  FlatList,
  ActivityIndicator,
  StyleSheet,
  RefreshControl
} from 'react-native';
import { fetchContacts, syncContacts } from '@contactsmanager/rn';

const ContactListScreen = () => {
  const [contacts, setContacts] = useState([]);
  const [isLoading, setIsLoading] = useState(false);
  const [isRefreshing, setIsRefreshing] = useState(false);
  
  useEffect(() => {
    loadContacts();
  }, []);
  
  const loadContacts = async () => {
    setIsLoading(true);
    
    try {
      const fetchedContacts = await fetchContacts();
      setContacts(fetchedContacts);
    } catch (error) {
      console.error('Error loading contacts:', error);
    } finally {
      setIsLoading(false);
    }
  };
  
  const handleRefresh = async () => {
    setIsRefreshing(true);
    
    try {
      await syncContacts();
      // Reload contacts after sync
      await loadContacts();
    } catch (error) {
      console.error('Error syncing contacts:', error);
    } finally {
      setIsRefreshing(false);
    }
  };
  
  const renderContactRow = ({ item }) => (
    <View style={styles.contactRow}>
      <Text style={styles.contactName}>{item.displayName || 'Unknown'}</Text>
      {item.phoneNumbers && item.phoneNumbers.length > 0 && (
        <Text style={styles.contactDetail}>{item.phoneNumbers[0].value}</Text>
      )}
    </View>
  );
  
  return (
    <View style={styles.container}>
      {isLoading ? (
        <View style={styles.loadingContainer}>
          <ActivityIndicator size="large" />
          <Text style={styles.loadingText}>Loading contacts...</Text>
        </View>
      ) : (
        <FlatList
          data={contacts}
          renderItem={renderContactRow}
          keyExtractor={(item) => item.id}
          refreshControl={
            <RefreshControl
              refreshing={isRefreshing}
              onRefresh={handleRefresh}
            />
          }
          ListEmptyComponent={
            <View style={styles.emptyContainer}>
              <Text style={styles.emptyText}>No contacts found</Text>
            </View>
          }
        />
      )}
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
  },
  loadingContainer: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  loadingText: {
    marginTop: 10,
    fontSize: 16,
    color: '#666',
  },
  contactRow: {
    padding: 15,
    borderBottomWidth: 1,
    borderBottomColor: '#f0f0f0',
  },
  contactName: {
    fontSize: 16,
    fontWeight: '600',
  },
  contactDetail: {
    fontSize: 14,
    color: '#666',
    marginTop: 4,
  },
  emptyContainer: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 50,
  },
  emptyText: {
    fontSize: 16,
    color: '#666',
  },
});

export default ContactListScreen;

// Coming Soon

// Coming Soon

Troubleshooting Offline Issues

Common Issues

Synchronization not completing
- Check for connectivity issues
- Ensure the SDK is properly initialized
- Verify that authentication tokens are valid
Unexpected data loss
- Ensure the app isn’t forcefully terminated during sync
- Verify that device storage isn’t critically low
- Check for permission changes while offline
Background sync issues
- Verify that you’ve called enableBackgroundSync() during app initialization
- Check that your app has the proper background modes enabled in capabilities
- Ensure you have the “Background Processing” entitlement for your app

Logging and Debugging

The ContactsManager SDK uses the OSLog system for logging important events. To view these logs, use the Console app on macOS with your device connected, and filter for the subsystem “com.contactsmanager”.

Get Started

Features

Services

Webhooks

Models

Offline Functionality

Offline Functionality

Offline-First Approach

Working with Contacts Offline

Fetching Contacts

Fetching a Single Contact

Synchronization Management

Manual Synchronization

Background Synchronization

Following Contacts

Implementing an Offline-Aware UI

Troubleshooting Offline Issues

Common Issues

Logging and Debugging

​Offline Functionality

​Offline-First Approach

​Working with Contacts Offline

​Fetching Contacts

​Fetching a Single Contact

​Synchronization Management

​Manual Synchronization

​Background Synchronization

​Social Features in Offline Mode

​Following Contacts

​Offline Limitations for Social Features

​Implementing an Offline-Aware UI

​Troubleshooting Offline Issues

​Common Issues

​Logging and Debugging

Offline Functionality

Offline-First Approach

Working with Contacts Offline

Fetching Contacts

Fetching a Single Contact

Synchronization Management

Manual Synchronization

Background Synchronization

Social Features in Offline Mode

Following Contacts

Offline Limitations for Social Features

Implementing an Offline-Aware UI

Troubleshooting Offline Issues

Common Issues

Logging and Debugging