Objective-C SDK for Contentful's Content Delivery API and Content Management API.
Objective-C Ruby Other
Clone or download
loudmouth Merge pull request #98 from contentful/update-readme
Add coverage comparison table to readme
Latest commit fe163e7 Jun 12, 2018
Permalink
Failed to load latest commit information.
ContentfulDeliveryAPI Fix nullability specifiers and import statements for Xcode9 compatibi… Sep 22, 2017
ContentfulSDK.xcodeproj Update gems and pods Jun 12, 2018
ContentfulSDK.xcworkspace Remove internal copy of the Realm persistence manager Feb 23, 2016
Examples Fix broken Seed databse Command line utility (#89) Sep 20, 2017
ManagementAPI Fix nullability specifiers and import statements for Xcode9 compatibi… Sep 22, 2017
ManagementTests Add platform section to x-contentful-header May 29, 2017
Screenshots Public release. Mar 17, 2014
Submodules Fix broken Seed databse Command line utility (#89) Sep 20, 2017
Tests Update asset domain Apr 11, 2018
docs New project structure to get jazzy to work May 12, 2017
scripts Script setting the version numbers, and add Versions.h to podspecs May 29, 2017
.env Fix broken Seed databse Command line utility (#89) Sep 20, 2017
.envrc Fix broken Seed databse Command line utility (#89) Sep 20, 2017
.gitignore Fix broken Seed databse Command line utility (#89) Sep 20, 2017
.gitmodules Change origin or persistence submodule to use https instead of ssh May 2, 2017
.slather.yml Enable code coverage for CDA and CMA May 17, 2017
.travis.yml Don't test CMA on travis as it's now deprecated Jun 12, 2018
ContentfulDeliveryAPI.podspec Fix broken Seed databse Command line utility (#89) Sep 20, 2017
ContentfulManagementAPI.podspec Script setting the version numbers, and add Versions.h to podspecs May 29, 2017
Gemfile Update gems and pods Jun 12, 2018
Gemfile.lock Update gems and pods Jun 12, 2018
LICENSE Public release. Mar 17, 2014
Makefile Specify simulator 10.3.1 to fix travis Jul 21, 2017
Podfile Update gems and pods Jun 12, 2018
Podfile.lock Update gems and pods Jun 12, 2018
README.md Port coverage table from swift sdk Jun 12, 2018
Versions.h Fix broken Seed databse Command line utility (#89) Sep 20, 2017
mgmt-README.md Add notices of CMA deprecation to READMEs Apr 11, 2018

README.md

contentful.objc

Version License Platform Build Status Coverage Status

Deprecation notice for ContentfulManagementAPI SDK

Contentful will stop supporting the ContentfulManagementAPI SDK JULY 13, 2018. The source code will still be available, but feature and support requests will no longer be addressed. If you must take advantage of a feature from the Content Management API, or fix a bug, it is recommended that you either fork this codebase, or implement API interaction your own.

It is recommended to use contentful.swift over contentful.objc as future development at Contentful will focus on Swift rather than Objective-C.

Full feature comparison of contentful.swift & contentful.objc

CDA Features contentful.swift contentful.objc
API coverage*
Images API
Search Parameters 🚫
Fallback locales for sync api 🚫
Rate limit handling 🚫
Space environments 🚫

*API Coverage definition: all endpoints can be interfaced with and complex queries can be constructed by passing in dictionaries of http parameter/argument pairs. Note that the Swift SDK provides much more comprehensive coverage and takes advantage of type system, outdoing the "stringly typed" interface that the Objective-C SDK offers.

Objective-C SDK's for Contentful's Content Delivery API.

Contentful provides a content infrastructure for digital teams to power content in websites, apps, and devices. Unlike a CMS, Contentful was built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enable developers and content creators to ship digital products faster.

Usage

The CDAClient manages all your interaction with the Contentful Delivery API.

CDAClient* client = [[CDAClient alloc] initWithSpaceKey:@"cfexampleapi" accessToken:@"b4c0n73n7fu1"];
[client fetchEntryWithIdentifier:@"nyancat"
                         success:^(CDAResponse *response, CDAEntry *entry) {
                             NSLog(@"%@", entry.fields);
                         }
                         failure:^(CDAResponse *response, NSError *error) {
                             NSLog(@"%@", error);
                         }];

You can query for entries, assets, etc. with query options similar to what is described in the Delivery API Documentation:

[client fetchEntriesMatching:@{ @"content_type": @"cat" }
                     success:^(CDAResponse *response, CDAArray *entries) {
                         NSLog(@"%@", [[entries.items firstObject] fields]);
                     }
                     failure:^(CDAResponse *response, NSError *error) {
                         NSLog(@"%@", error);
                     }];

Results are returned as object of classes CDAEntry, CDAAsset, CDAContentType or CDASpace, depending on the fetch method being called. If there are multiple results, they will be returned as a CDAArray instance, which encapsulates the actual resources in the items property.

This repository contains multiple examples, demonstrating the use in common real world scenarios and also showing the different ways you can integrate the SDK into your own project.

Using Custom Entry Classes

You might want to subclass CDAEntry to store additional data alongside Entries or to decouple the rest of your app from the Contentful SDK's API. For this purpose, it is possible to register your own custom classes for specific Content Types, like this:

[client registerClass:[MYSuperCoolClass class] forContentTypeWithIdentifier:@"MyContentType"];

Each time, the receiver needs to create a new Entry object of the given Content Type, it will create instances of MYSuperCoolClass. Make sure that the class inherits from CDAEntry or this mechanism will break at runtime.

Offline Support

Mobile devices will not always have a data connection, so it makes sense to cache data received from Contentful for offline use. The SDK brings two mechanisms which can help with that:

All Resource classes support NSCoding and bring convenience methods for storing and loading from flat files:

[someEntry writeToFile:@"/some/path"];
CDAEntry* readEntry = [CDAEntry readFromFile:@"/some/path" client:client];

Most of the UIKit extensions have an offlineCaching property which transparently uses this mechanism for showing content when offline.

If you rather use another solution, there is the abstract CDAPersistenceManager class with a sample implementation for Core Data. It supports mapping Resources to another method for managing your object graph easily and ties this to the Contentful synchronization API. Check out the Core Data example app for integrating it yourself.

In both cases, you can use the offlineCaching_cda property of the SDK's UIImageView category to make any image view transparently cache its contents in a flat file on disk. This will only cache images that the user has viewed once while the app was online.

Preview Mode

The Content Delivery API only returns published Entries. However, you might want to preview content in your app before making it public for your users. For this, you can use the preview mode, which will return all Entries, regardless of their published status:

CDAConfiguration* configuration = [CDAConfiguration defaultConfiguration];
configuration.previewMode = YES;

CDAClient* client = [[CDAClient alloc] initWithSpaceKey:@"YourSpaceKey"
                                            accessToken:@"YourAccessToken"
                                          configuration:configuration];

Apart from the configuration option, you can use the SDK without modifications with one exception: you need to obtain a preview access token, which you can get in the "API" tab of the Contentful app. In preview mode, data can be invalid, because no validation is performed on unpublished entries. Your app needs to deal with that. Be aware that the access token should in no case be shipped with a production app.

UIKit Extensions

The SDK contains some extensions of UIKit classes for common use cases. You can see a lot of them in action in the examples or read this blog post with details on some of them.

Documentation

For further information, check out the Developer Documentation or browse the API documentation. The latter can also be loaded into Xcode as a Docset.

Installation

CocoaPods

CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries like the Contentful Delivery API in your projects.

platform :ios, '8.0'
pod 'ContentfulDeliveryAPI'

This is the easiest way to keep your copy of the Contentful Delivery API updated.

For Swift support using iOS 8, you can enable framework support usage in CocoaPods:

platform :ios, '8.0'
use_frameworks!
pod 'ContentfulDeliveryAPI'

Manual integration

In the case you prefer to manage your dependencies manually, you can just drag all files from the Code subdirectory into your project or integrate the ContentfulDeliveryAPI static library target into your build process. It might be a good idea to add this repository as a Git submodule if you choose this path.

Be aware that the Contentful Delivery API requires both AFNetworking and ISO8601 to compile successfully, so you need to provide these dependencies if you do manual integration.

Static Framework

You can download the Contentful Delivery API as an universal static framework for iOS. Integrate it into your project by unzipping and dragging the ContentfulDeliveryAPI.framework into the Frameworks group of your project. You can also download the UFO example application including the static framework, as an example of integrating it into an Xcode project.

The static framework contains AFNetworking and ISO8601, but they are prefixed so that they do not clash with any copies that might already be part of your application.

It depends on the SystemConfiguration.framework not included by default in iOS projects, so open your project file on the General tab.

Click the + button in the Linked Frameworks and Libraries section at the bottom.

Search for SystemConfiguration and add the framework to your project.

Repeat that with MobileCoreServices, as that framework is also required to be in your project.

Unit Tests

The Contentful Delivery API is fully unit tested.

To run the tests, do the following steps:

$ gem install xcpretty cocoapods cocoapods-testing
$ make test

or run them directly from Xcode.

License

Copyright (c) 2014, 2015 Contentful GmbH. See LICENSE for further details.