Onymos Raises $12M Series A: Learn why

onymos-logo
contact icon

Quickstart Guide: Contacts Component

Contacts Component

Select a framework to get started.

Get started

Using Ionic or Cordova? Get the Contacts component working in your app in four easy steps.

  1. Download the component
  2. Add it to your environment
  3. Using Contacts
  4. Troubleshoot

1. Download the Onymos Contacts component

Sign up! We’ll send you a link to your component, set up your Onymos Cloud Account, and generate your Onymos license credentials. In the meantime, you can get familiar with our API Documentation and developer resources, or join a whole community of developers building apps with Onymos on Reddit!

2. Add it to your environment

Add your components to a folder in your app’s root (e.g., onymos_components).

Add the Onymos Initialize component to your environment.

$ cordova plugin add onymos_components/onymos-component-initialize

Then we can add the Onymos Contacts component.

$ cordova plugin add onymos_components/onymos-component-contacts

Then update the widget inside your config.xml with the Onymos Widget ID you receive after you create an Onymos Cloud Account.

3. Using Contacts

Using the Contacts component in your app
Apps are better with friends—use the Onymos Contacts component so your users can import all of theirs! Filter by names, addresses, phone numbers, emails, and more. With its intelligent loading and in-memory manipulation, Contacts can keep up with even the most gregarious userbase.

Before we use Contacts, let’s make sure we have everything we need to configure your onymosConnectObject. The onymosConnectObject requires the appropriate Onymos license credentials: your Customer ID (also called an Onymos ID) and your Onymos Auth Token. You’ll need these credentials to use this (or any) component in your app. To generate your Onymos license credentials, create an Onymos Cloud Account.

NOTE: Your Onymos license credentials will work with any number of apps and components. Onymos has a developer—and project—friendly pricing model. You can use any or all of our components in an app at no cost until it is installed on 100 or more devices. This is ideal for iterating your MVP (see detailed pricing here).

Next, let’s go inside your Cordova app’s index.js file and initialize Contacts.

var OnymosInitalize
var OnymosContacts

document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
  const OnymosConnectObject={
    customerId : 'Your customerId goes here', 
    onymosAuthToken : 'Your onymosAuthToken goes here',  
    envType: 'PRD'
  }

  OnymosInitialize.initialize(
    OnymosConnectObject,
      
    function onymosInitializeSuccess(status){
      console.log("Onymos initialized Successfully.", status)
    },

    function onymosInitializeFailure(error){
      console.log("Onymos failed to initialize.", error)
    })
}

Great! If we configured your onymosConnectObject correctly, onymosInitializeSuccess() should print its message to the console. Now we’re ready to use Contacts. Let’s create a function called getContactsList() in the index.js file, then your users will be able to start importing their contacts.

getContactsList() {
  OnymosContacts.getList(
    callId,

    function getContactsListSuccess(listOfContactsArray){
      listOfContactsArray [] = {
        // Array of Contacts
        // Fields as requested in options.displayFields
      }
    }

    function getContactsListFailure(error){
      console.log(error)
    },
    
    options)
}

Your callId will be a string that identifies your call to select a list of contacts (e.g., ‘1’).

The getList() method also includes optional parameters you can define to meticulously filter the contacts imported into your app. Let’s take a closer look at the options object. You can find out even more by checking out Contact’s API documentation.

{
  filter: 'A filter string applied to either a "Given name" (First name), or "Family name" (Last name).',
  searchField: 'Defines whether your filter will be applied to first or last names (e.g., OnymosContactsConstants.SearchField.givenName).',
  hasPhoneNumber: 'A boolean that when set to true only returns those contacts with phone numbers.',
  displayFields: 'An array of fields you want fetched for each contact returned. See a full list of these fields in Contact's API Documentation.',
  numberOfRecrods: 'An integer that defines how many contacts you want the method to return. Its default value is 100.'
}

Let’s actually configure the getList() method.

getContactsList() {
    OnymosMedia.getList(
      '1',
  
      function getContactsListSuccess(listOfContactsArray){
        console.log(listOfContactsArray)
      }
  
      function getContactsListFailure(error){
        console.log(error)
      },
      
      {
        filter: ‘Jo’,
        hasPhoneNumber: true,
        searchField: OnymosContactsConstants.SearchField.givenName,
        displayFields: [
          OnymosContactsConstants.DisplayFields.name,
          OnymosContactsConstants.DisplayFields.nickname,
          OnymosContactsConstants.DisplayFields.phoneNumbers,
          OnymosContactsConstants.DisplayFields.emails,
          OnymosContactsConstants.DisplayFields.addresses,
          OnymosContactsConstants.DisplayFields.note
        ],
        numberOfRecords: 200
      })
  }
 

Now your app is filled with contacts… and you just have to decide what to do with them all!

Wait, what if a user has more than 200 contacts? Well, wow, but don’t worry, you can use the loadNextSet() method to import them too.

4. Troubleshooting

How do I squash this bug? Is Ionic supposed to do that? Why is this iOS build failing?

Let’s figure it out—join the Onymos community on Reddit! More of a loner? You can email us directly at customersuccess@onymos.com.

Dig into our API documentation

Developer support

Got questions? Our support team is here to help.

Think differently about app development

Download our free white paper today to learn how Onymos Features can maximize the value of your developer resources — and shave days or weeks off your development timeline.

Get your free white paper