Arkio for Data.com

Arkio is an Objective-C client library for Data.com.

1. Features

• Full implementation of the Data.com Connect API. (PDF)
• XCText unit test suite.
• CocoaPods integration.
• Complete AppleDocs with a build to install the docset in Xcode.
• Built on top of AFNetworking 2.0.

2. API Overview

Full implementation of the Data.com Connect API means that you are able to do the following with Arkio:

• Search for Contacts.
• Purchase and download Contacts.
• Retrieve a Company's Contact Count Statistics.
• Retrieve a User's point balance.

3. Requirements

Arkio is written for ARC-enabled apps. By default your build target will need to comply with one of the following:

• iOS 6 or later
• OS X 10.8 and later

If you aren't using ARC, you can still use Arkio by specifying the -fobjc-arc compiler flag for the implementation files (*.m) in your target's Compile Sources section of the Build Phases tab.

4. Installation

Arkio depends on CocoaPods in order to build successfully. Installation via CocoaPods is the only recommended way of integrating Arkio with your project. Why? Arkio depends on AFNetworking, and that is most easily available via CocoaPods.

CocoaPods

Simply add the following line to your project's Podfile:

pod 'Arkio'

then, at the command line, from the same directory as your Podfile, run

pod install

Bear in mind that you will not get the unit test suite or the ability to install the AppleDoc docset locally if simply integrating Arkio with your project as explained above.

Unit Tests & the Docset

If you would like to install the included AppleDocs docset locally so the docset appears in the Xcode Documentation Viewer, or view and run the XCTest unit test suite you will need to clone the repo from GitHub to your local machine. You will need to run the CocoaPods command pod install in the root directory of the repo before building the "Install AppleDocs" target for the project. By default, the docset is installed to the "~/Library/Developer/Shared/Documentation/DocSets" location with the package name of "com.alienhitcher.Arkio.docset".

5. Configuration

To interface successfully with the Data.com API you will need a Developer Token/Key. The easiet way to configure Arkio is to add your developer token to you app's Info.plist file as the value for the key "arkio.api.developer.token", as below:

This allows ARKSession instances to pick up the value automatically. Alternately, you can set the token value directly on the session as below:

[arkSession setAPIDeveloperToken:@"developertokentext"];

6. Coding Quick Start

After installation and configuration, import the library header file somewhere sensible in your code:

#import "Arkio.h"

Then, initialize an ARKSession with a valid Data.com username and password, and use the methods on the session to interface with the API.

    ARKSession *session = [[ARKSession alloc] initWithUsername:@"[email protected]" 
                                                      password:@"foobar"];

    [session userInformation:^(long points, ARKError *error) {

        if (!error) {
            NSLog(@"points = %ld ", points);
        }
        else {
            // we receive an application error message from Data.com
            NSLog(@"ark error: %@", error);
        }
    }
                     failure:^(NSError *error) {
                         // an unexpected HTTP network error occurred
                         NSLog(@"failed with network error: %@", error);
                     }
    ];

7. Unit Tests

Cloning the repo from GitHub will give you access to the XCTest unit tests. They live in the ArkioTests folder, and are a good place to find working examples of using Arkio.

Configure

The tests require 3 configuration settings before they'll run against a Data.com API endpoint. Navigate to the "ArkioTests/Supporting Files" folder and add values for the following keys in the ArkioTests-Info.plist file:

• arkio.api.developer.token
• arkio.account.username
• arkio.account.password

Parameters for the API calls made in the unit tests are stored in the supporting file named ArkioTestData.plist.

Build

You will need to run the CocoaPods command pod install in the root directory of the repo before building for testing with ⇧⌘U.

8. Reference Documentation

• The class reference documentation can be found on Cocoadocs.org.
• Official Data.com Connect API Documentation (PDF) from the Data.com Connect Developer Program.

Contact

Arkio is maintained by Ray Scott (@rayascott).

License

Arkio is available under the MIT license. For more information, see the included LICENSE file.