Stack

View as Markdown

Stack

Stack represents one stack and one environment in the iOS Delivery SDK. Every other object you use comes from a stack. Use this class to

  • open content types, assets, the asset library, taxonomies, and global fields
  • add headers that every request of the stack sends
  • list the content types of the stack with their schema
  • synchronize published content with the Synchronization API
  • add image transformation parameters to an asset URL

[[Stack alloc] init] and Stack() do not compile, because init is unavailable. Create a stack with the stackWithAPIKey:accessToken:environmentName: or stackWithAPIKey:accessToken:environmentName:config: method of Contentstack.

NameTypeDescription
apiKey NSString *

Read-only. API key of the stack.

accessToken NSString *

Read-only. Delivery token of the environment.

environment NSString *

Read-only. Environment that fetch, find, and initial sync calls send.

config Config *

Read-only. The same Config object you passed, not a copy.

hostURL NSString *

Read-only. The current host of config. Follows a change to config.region or config.host.

addHeadersWithDictionary:

addHeadersWithDictionary: adds several headers to every later request of the stack, and replaces any header with the same name.

NameTypeDescription
headers (required)NSDictionary<NSString *, NSString *> *

Header names mapped to their values.

Default: Not applicable

Returns: void. Nothing. The stack sends the headers with every later request.

Validation

  • There is no client-side validation of the names or the values.
  • A nil or empty headers dictionary adds nothing.
  • A header that the API rejects surfaces in the error argument of the completion block of the next fetch, find, or sync call.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • Client-side only. addHeadersWithDictionary: makes no request.
  • The SDK copies each pair into the stack headers, the same as one setHeader:forKey: call per pair. Headers already on the stack and not in headers stay.
  • The headers go on every later request of the stack and of every object that the stack creates.
  • The SDK sets X-User-Agent, User-Agent, and, when config.branch has a value, branch after your headers, so those names keep the SDK values.

Example

Basic usage: add two custom headers (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack addHeadersWithDictionary:@{@"My-Custom-Header": @"MyValue", @"My-Trace-Id": @"TRACE_ID"}];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Basic usage: add two custom headers (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.addHeaders(with: ["My-Custom-Header": "MyValue", "My-Trace-Id": "TRACE_ID"])
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

asset

asset creates an empty asset object, which you fill from an asset dictionary that you already have.

Returns: Asset. A new asset object with no UID.

Validation

  • There is no client-side validation. asset returns no error.
  • The object has no UID, so its fetch: method requests /v3/assets/(null) and the completion block receives the error of the API. Use the assetWithUID: method to fetch an asset.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • Client-side only. asset makes no request.
  • Each call returns a new Asset that uses the network session and headers of this stack.
  • Call the configureWithDictionary: method to fill the asset from a dictionary, for example the value of a file field in an entry. The asset takes its UID and other properties from the dictionary.
  • For a file field of an entry, the assetForKey: method of Entry returns the filled asset in one call.

Example

Basic usage: build an asset from a file field of an entry (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    Asset *asset = [stack asset];
    [asset configureWithDictionary:[entry objectForKey:@"banner_image"]];
    NSLog(@"%@ %@", asset.fileName, asset.url);
}];

Basic usage: build an asset from a file field of an entry (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    guard let file = entry.object(forKey: "banner_image") as? [String: Any] else { return }
    let asset = stack.asset()
    asset.configure(with: file)
    print(asset.fileName, asset.url)
}

assetLibrary

assetLibrary opens the assets of the stack, so you can list and filter them.

Returns: AssetLibrary. A new asset library object for this stack.

Validation

  • There is no client-side validation. assetLibrary returns no error.
  • Errors come from the fetch call that follows, in the error argument of its completion block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • Client-side only. assetLibrary makes no request.
  • Each call returns a new AssetLibrary that uses the network session and headers of this stack.
  • Next, call the fetchAll: method to list the assets through Get all assets.

Example

Basic usage: list the assets (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
AssetLibrary *assetLibrary = [stack assetLibrary];
[assetLibrary fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (Asset *asset in result) {
        NSLog(@"%@ %@", asset.fileName, asset.url);
    }
}];

Basic usage: list the assets (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let assetLibrary = stack.assetLibrary()
assetLibrary.fetchAll { (type, result, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for asset in result ?? [] {
        print(asset.fileName, asset.url)
    }
}

assetWithUID:

assetWithUID: opens one asset by its UID, so you can fetch it.

NameTypeDescription
uid (required)NSString *

UID of the asset.

Default: Not applicable

Returns: Asset. A new asset object for the given UID.

Validation

  • There is no client-side validation. assetWithUID: stores an unknown UID as given.
  • A nil or empty uid leaves the object with no UID, the same as the asset method.
  • An unknown UID surfaces in the error argument of the completion block of the fetch call that follows.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • Client-side only. assetWithUID: makes no request.
  • Each call returns a new Asset that uses the network session and headers of this stack.
  • Next, call the fetch: method to read the asset through Get a single asset.

Example

Basic usage: fetch one asset (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Asset *asset = [stack assetWithUID:@"ASSET_UID"];
[asset fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@ %@", asset.fileName, asset.url);
}];

Basic usage: fetch one asset (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let asset = stack.asset(withUID: "ASSET_UID")
asset.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(asset.fileName, asset.url)
}

contentTypeWithName:

contentTypeWithName: opens a content type by its UID, so you can fetch its entries or its schema.

NameTypeDescription
contentTypeName (required)NSString *

UID of the content type.

Default: Not applicable

Returns: ContentType. A new content type object for the given UID.

Validation

  • There is no client-side validation. contentTypeWithName: stores an empty or unknown UID as given.
  • An unknown UID surfaces in the error argument of the completion block of the fetch or find call that follows.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • Client-side only. contentTypeWithName: makes no request.
  • Each call returns a new ContentType that uses the network session and headers of this stack.
  • The UID goes into the request path of each call you make from the content type, for example /v3/content_types/<UID>/entries.
  • Next, call the entryWithUID: method to open one entry, the query method to find entries, or the fetch:completion: method to read the schema.

Example

Basic usage: open a content type and fetch an entry (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
ContentType *contentType = [stack contentTypeWithName:@"CONTENT_TYPE_UID"];
Entry *entry = [contentType entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Basic usage: open a content type and fetch an entry (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let contentType = stack.contentType(withName: "CONTENT_TYPE_UID")
let entry = contentType.entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

Query entries: find the entries of a content type (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] query];
[query find:^(ResponseType type, QueryResult *result, NSError *error) {
    if (error) { return; }
    for (Entry *entry in [result getResult]) {
        NSLog(@"%@", entry.title);
    }
}];

Query entries: find the entries of a content type (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.contentType(withName: "CONTENT_TYPE_UID").query()
query.find { (type, result, error) in
    guard error == nil else { return }
    for entry in result?.getResult() ?? [] {
        print(entry.title)
    }
}

getContentTypes:completion:

getContentTypes:completion: lists the content types of the stack, with the schema of each one.

NameTypeDescription
paramsNSDictionary<NSString *, id> *

Query parameters to add to the request.

Default: nil
completionBlock (required)void (^)(NSArray<NSString *> *, NSError *)

Receives the content types, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.
  • When the response has no content_types array, the completion block receives an NSError with domain Error, code -4001, and a message under userInfo[@"error"].

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • One call sends one Get all content types request, GET /v3/content_types, with each pair in params as a query parameter. The SDK adds no environment parameter.
  • The API reference lists include_count and include_branch for this request, and the include_global_field_schema parameter to return the schema of each global field inside a content type. Pass @"true" as the value.
  • The completion block receives only the content_types array of the response. Each element is an NSDictionary for one content type, although the header declares NSArray<NSString *> *. Read the elements as dictionaries.
  • The SDK drops the other keys of the response, so the count that include_count adds does not reach you. Count the array instead.
  • The request always goes to the network and never uses the cache.
  • To read one content type, call the fetch:completion: method of ContentType.

Example

Basic usage: list content types with their global field schema (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack getContentTypes:@{@"include_global_field_schema": @"true"} completion:^(NSArray *contentTypes, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    // Each element is a dictionary for one content type.
    for (NSDictionary *contentType in contentTypes) {
        NSLog(@"%@ %@", contentType[@"uid"], contentType[@"title"]);
    }
}];

Basic usage: list content types with their global field schema (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
// The SDK declares the array as [String] but fills it with dictionaries.
// Pass your own block through perform, so Swift reads the elements as dictionaries.
let completion: @convention(block) (NSArray?, NSError?) -> Void = { contentTypes, error in
    if let error = error {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for case let contentType as [String: Any] in contentTypes ?? [] {
        print(contentType["uid"] ?? "", contentType["title"] ?? "")
    }
}
_ = stack.perform(NSSelectorFromString("getContentTypes:completion:"), with: ["include_global_field_schema": "true"], with: completion)

getHeaders

getHeaders returns a copy of the headers that the stack adds to every request.

Returns: NSDictionary. A copy of the headers that the stack sends with every request.

Validation

  • There is no client-side validation. getHeaders returns no error.

Behavior

  • Client-side only. getHeaders makes no request.
  • The dictionary contains api_key and access_token, x-header-ea when the Config requests early access features, and every header that you add with setHeader:forKey: or addHeadersWithDictionary:.
  • It does not contain the headers that the SDK sets on each request: X-User-Agent, User-Agent, x-cs-retry-count, and the branch header from config.branch.
  • The dictionary is a copy. Changing it does not change the stack headers.
  • The dictionary includes the delivery token. Do not log it in production builds.

Example

Basic usage: print the stack headers (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack setHeader:@"MyValue" forKey:@"My-Custom-Header"];
NSDictionary *headers = [stack getHeaders];
for (NSString *name in headers) {
    NSLog(@"%@", name);
}

Basic usage: print the stack headers (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.setHeader("MyValue", forKey: "My-Custom-Header")
let headers = stack.getHeaders()
for name in headers.keys {
    print(name)
}

globalField

globalField opens the global fields of the stack, so you can list them.

Returns: GlobalField. A new global field object with no UID.

Validation

  • There is no client-side validation. globalField returns no error.
  • Errors come from the fetch call that follows, in the error argument of its completion block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • Client-side only. globalField makes no request.
  • Each call returns a new GlobalField with no UID, which uses the network session and headers of this stack.
  • Next, call the fetchAll: method to list the global fields through Get all global fields.
  • To read one global field, use the globalFieldWithName: method instead.
  • The Objective-C example imports <Contentstack/GlobalField.h> as well, because Contentstack.h does not import it.

Example

Basic usage: list the global fields (Objective-C)

#import <Contentstack/Contentstack.h>
#import <Contentstack/GlobalField.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
GlobalField *globalField = [stack globalField];
[globalField fetchAll:^(ResponseType type, NSArray<GlobalField *> *result, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (GlobalField *field in result) {
        NSLog(@"%@ %@", field.uid, field.title);
    }
}];

Basic usage: list the global fields (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let globalField = stack.globalField()
globalField.fetchAll { (type, result, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for field in result ?? [] {
        print(field.uid, field.title)
    }
}

globalFieldWithName:

globalFieldWithName: opens one global field by its UID, so you can fetch it.

NameTypeDescription
globalFieldName (required)NSString *

UID of the global field.

Default: Not applicable

Returns: GlobalField. A new global field object for the given UID.

Validation

  • There is no client-side validation. globalFieldWithName: stores an unknown UID as given.
  • A nil or empty globalFieldName leaves the object with no UID, the same as the globalField method.
  • An unknown UID surfaces in the error argument of the completion block of the fetch call that follows.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • Client-side only. globalFieldWithName: makes no request.
  • Each call returns a new GlobalField that uses the network session and headers of this stack.
  • Next, call the fetch: method to read the global field through Get a single global field.
  • The Objective-C example imports <Contentstack/GlobalField.h> as well, because Contentstack.h does not import it.

Example

Basic usage: fetch one global field (Objective-C)

#import <Contentstack/Contentstack.h>
#import <Contentstack/GlobalField.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
GlobalField *globalField = [stack globalFieldWithName:@"GLOBAL_FIELD_UID"];
[globalField fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", globalField.title);
}];

Basic usage: fetch one global field (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let globalField = stack.globalField(withName: "GLOBAL_FIELD_UID")
globalField.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(globalField.title)
}

imageTransformWithUrl:andParams:

imageTransformWithUrl:andParams: appends Image Delivery API parameters to an image URL, so the image loads resized, cropped, or converted.

NameTypeDescription
url (required)NSString *

URL of the image asset.

Default: Not applicable
params (required)NSDictionary<NSString *, id> *

Transformation parameter names mapped to their values.

Default: Not applicable

Returns: NSString. The image URL that ends with the transformation parameters.

Validation

  • There is no client-side validation. The SDK appends any name and value as given.
  • An empty params dictionary returns url with a trailing ? when url has no query string.
  • A parameter that the Image Delivery API rejects surfaces when your app loads the URL, not here.

Behavior

  • Client-side only. imageTransformWithUrl:andParams: makes no request. Load the returned URL with your own image loader.
  • When url has no ?, the SDK adds one. It then appends each pair as name=value and joins the pairs with &. A url that already has a query string keeps it.
  • The SDK writes each value with its description, so @100 becomes 100. Pass values in the form the Image Delivery API expects, for example @"300,400" for crop.
  • The SDK does not percent-encode names or values. It removes every space from the whole URL, including spaces in url.
  • The order of the parameters follows the order of the dictionary, which NSDictionary does not fix.
  • The SDK adds no environment parameter. The Image Delivery API reference lists environment as a query parameter of each transformation request, so add it to params when your asset URL needs it.
  • The Resize Images, Control Quality, and Convert Formats sections of the Image Delivery API reference describe width, height, quality, and format.

Example

Basic usage: resize an image and convert it to WebP (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Asset *asset = [stack assetWithUID:@"ASSET_UID"];
[asset fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSDictionary *params = @{@"width": @300, @"height": @200, @"quality": @80, @"format": @"webp"};
    NSString *transformedUrl = [stack imageTransformWithUrl:asset.url andParams:params];
    NSLog(@"%@", transformedUrl);
}];

Basic usage: resize an image and convert it to WebP (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let asset = stack.asset(withUID: "ASSET_UID")
asset.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    let params: [String: Any] = ["width": 300, "height": 200, "quality": 80, "format": "webp"]
    let transformedUrl = stack.imageTransform(withUrl: asset.url, andParams: params)
    print(transformedUrl)
}

removeHeaderForKey:

removeHeaderForKey: removes one header from the stack, so later requests no longer send it.

NameTypeDescription
headerKey (required)NSString *

Name of the header to remove.

Default: Not applicable

Returns: void. Nothing. The stack stops sending the header.

Validation

  • There is no client-side validation. A name that the stack does not hold, or nil, does nothing.
  • Removing api_key or access_token makes later requests fail. The API rejection surfaces in the error argument of the completion block of the next fetch, find, or sync call.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • Client-side only. removeHeaderForKey: makes no request.
  • It removes the header from the stack headers only. A header that an entry, query, or other object sets for itself stays on that object's requests.
  • It cannot remove X-User-Agent, User-Agent, or the branch header that config.branch adds, because the SDK sets those on each request.
  • Removing x-header-ea stops the early access header that a Config added.

Example

Basic usage: stop sending a custom header (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack setHeader:@"MyValue" forKey:@"My-Custom-Header"];
[stack removeHeaderForKey:@"My-Custom-Header"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Basic usage: stop sending a custom header (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.setHeader("MyValue", forKey: "My-Custom-Header")
stack.removeHeader(forKey: "My-Custom-Header")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

setHeader:forKey:

setHeader:forKey: adds one header to every later request of the stack, or replaces the header with the same name.

NameTypeDescription
headerValue (required)NSString *

Value of the header.

Default: Not applicable
headerKey (required)NSString *

Name of the header.

Default: Not applicable

Returns: void. Nothing. The stack sends the header with every later request.

Validation

  • There is no client-side validation of the name or the value.
  • A nil headerValue or headerKey raises NSInvalidArgumentException, because the SDK stores headers in a dictionary that rejects nil.
  • A header that the API rejects surfaces in the error argument of the completion block of the next fetch, find, or sync call.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • Client-side only. setHeader:forKey: makes no request.
  • The header goes on every later request of the stack and of every object that the stack creates, including objects you created before this call.
  • The value is the first argument and the name is the second. Swapping them sends a header whose name is your value.
  • Setting api_key or access_token replaces the credential that the stack sends. The apiKey and accessToken properties keep the constructor values.
  • A header that an entry, query, or other object sets for itself replaces a stack header of the same name on that object's requests.
  • The SDK sets X-User-Agent, User-Agent, and, when config.branch has a value, branch after your headers, so those names keep the SDK values.

Example

Basic usage: add a custom header to every request (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack setHeader:@"MyValue" forKey:@"My-Custom-Header"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Basic usage: add a custom header to every request (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.setHeader("MyValue", forKey: "My-Custom-Header")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

sync:

sync: syncs every entry and asset published to the environment of the stack, as the first step of keeping a local copy up to date.

NameTypeDescription
completionBlock (required)void (^)(SyncStack *, NSError *)

Receives each page of the result, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • One call starts an Initial Sync request, GET /v3/stacks/sync, with init=true and the environment of the stack. It sends no filter.
  • The API returns the published entries and assets of the environment. Run this once, when the app has no content yet.
  • While a response includes a pagination_token, the SDK requests the next page and runs the completion block once for each page. On the last page, syncToken contains the sync token. See Sync on the Stack class page.
  • Store the syncToken of the last page, and pass it to the syncToken:completion: method on the next run.
  • To sync part of the content, use a method that takes a filter, such as syncOnly:completion: or syncFrom:completion:.

Example

Basic usage: sync all published content (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack sync:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
    if (syncStack.syncToken) {
        // The last page carries the sync token. Store it for the next sync.
        NSLog(@"Sync token: %@", syncStack.syncToken);
    }
}];

Basic usage: sync all published content (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.sync { (syncStack, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
    if let token = syncStack?.syncToken {
        // The last page carries the sync token. Store it for the next sync.
        print("Sync token: \(token)")
    }
}

syncFrom:completion:

syncFrom:completion: syncs the entries and assets published from a given date onward.

NameTypeDescription
date (required)NSDate *

Start date of the content to sync.

Default: Not applicable
completionBlock (required)void (^)(SyncStack *, NSError *)

Receives each page of the result, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • A nil date raises NSInvalidArgumentException before any request, because the SDK builds the request parameters with a dictionary literal.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • One call starts an Initial Sync request, GET /v3/stacks/sync, with init=true, the environment of the stack, and start_from.
  • The SDK sends date in start_from as an ISO 8601 date and time in the time zone of the device. The value ends with the offset from UTC, for example 2026-01-15T09:30:00+0530.
  • While a response includes a pagination_token, the SDK requests the next page and runs the completion block once for each page. On the last page, syncToken contains the sync token. See Sync on the Stack class page.
  • Store the syncToken of the last page, and pass it to the syncToken:completion: method on the next run.

Example

Basic usage: sync the content published in the last seven days (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
NSDate *date = [NSDate dateWithTimeIntervalSinceNow:-7 * 24 * 60 * 60];
[stack syncFrom:date completion:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
    if (syncStack.syncToken) {
        // The last page carries the sync token. Store it for the next sync.
        NSLog(@"Sync token: %@", syncStack.syncToken);
    }
}];

Basic usage: sync the content published in the last seven days (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let date = Date(timeIntervalSinceNow: -7 * 24 * 60 * 60)
stack.sync(from: date) { (syncStack, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
    if let token = syncStack?.syncToken {
        // The last page carries the sync token. Store it for the next sync.
        print("Sync token: \(token)")
    }
}

syncLocale:completion:

syncLocale:completion: syncs the entries and assets published in one locale.

NameTypeDescription
locale (required)NSString *

Locale code to sync, such as en-us.

Default: Not applicable
completionBlock (required)void (^)(SyncStack *, NSError *)

Receives each page of the result, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • A nil locale raises NSInvalidArgumentException before any request, because the SDK builds the request parameters with a dictionary literal.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • One call starts an Initial Sync request, GET /v3/stacks/sync, with init=true, the environment of the stack, and locale.
  • While a response includes a pagination_token, the SDK requests the next page and runs the completion block once for each page. On the last page, syncToken contains the sync token. See Sync on the Stack class page.
  • Store the syncToken of the last page, and pass it to the syncToken:completion: method on the next run.

Example

Basic usage: sync one locale (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack syncLocale:@"en-us" completion:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
    if (syncStack.syncToken) {
        // The last page carries the sync token. Store it for the next sync.
        NSLog(@"Sync token: %@", syncStack.syncToken);
    }
}];

Basic usage: sync one locale (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.syncLocale("en-us") { (syncStack, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
    if let token = syncStack?.syncToken {
        // The last page carries the sync token. Store it for the next sync.
        print("Sync token: \(token)")
    }
}

syncLocale:from:completion:

syncLocale:from:completion: syncs the entries and assets published in one locale from a given date onward.

NameTypeDescription
locale (required)NSString *

Locale code to sync, such as en-us.

Default: Not applicable
date (required)NSDate *

Start date of the content to sync.

Default: Not applicable
completionBlock (required)void (^)(SyncStack *, NSError *)

Receives each page of the result, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • A nil locale or date raises NSInvalidArgumentException before any request, because the SDK builds the request parameters with a dictionary literal.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • One call starts an Initial Sync request, GET /v3/stacks/sync, with init=true, the environment of the stack, locale, and start_from.
  • The SDK sends date in start_from as an ISO 8601 date and time in the time zone of the device. The value ends with the offset from UTC, for example 2026-01-15T09:30:00+0530.
  • While a response includes a pagination_token, the SDK requests the next page and runs the completion block once for each page. On the last page, syncToken contains the sync token. See Sync on the Stack class page.
  • Store the syncToken of the last page, and pass it to the syncToken:completion: method on the next run.

Example

All parameters: sync one locale from last week (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
NSDate *date = [NSDate dateWithTimeIntervalSinceNow:-7 * 24 * 60 * 60];
[stack syncLocale:@"en-us" from:date completion:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
    if (syncStack.syncToken) {
        // The last page carries the sync token. Store it for the next sync.
        NSLog(@"Sync token: %@", syncStack.syncToken);
    }
}];

All parameters: sync one locale from last week (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let date = Date(timeIntervalSinceNow: -7 * 24 * 60 * 60)
stack.syncLocale("en-us", from: date) { (syncStack, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
    if let token = syncStack?.syncToken {
        // The last page carries the sync token. Store it for the next sync.
        print("Sync token: \(token)")
    }
}

syncOnly:completion:

syncOnly:completion: syncs the published entries of one content type.

NameTypeDescription
contentType (required)NSString *

UID of the content type to sync.

Default: Not applicable
completionBlock (required)void (^)(SyncStack *, NSError *)

Receives each page of the result, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • A nil contentType raises NSInvalidArgumentException before any request, because the SDK builds the request parameters with a dictionary literal.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • One call starts an Initial Sync request, GET /v3/stacks/sync, with init=true, the environment of the stack, and content_type_uid.
  • contentType takes one UID. Run one sync for each content type you need.
  • While a response includes a pagination_token, the SDK requests the next page and runs the completion block once for each page. On the last page, syncToken contains the sync token. See Sync on the Stack class page.
  • Store the syncToken of the last page, and pass it to the syncToken:completion: method on the next run.

Example

Basic usage: sync one content type (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack syncOnly:@"CONTENT_TYPE_UID" completion:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
    if (syncStack.syncToken) {
        // The last page carries the sync token. Store it for the next sync.
        NSLog(@"Sync token: %@", syncStack.syncToken);
    }
}];

Basic usage: sync one content type (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.syncOnly("CONTENT_TYPE_UID") { (syncStack, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
    if let token = syncStack?.syncToken {
        // The last page carries the sync token. Store it for the next sync.
        print("Sync token: \(token)")
    }
}

syncOnly:from:completion:

syncOnly:from:completion: syncs the entries of one content type published from a given date onward.

NameTypeDescription
contentType (required)NSString *

UID of the content type to sync.

Default: Not applicable
date (required)NSDate *

Start date of the content to sync.

Default: Not applicable
completionBlock (required)void (^)(SyncStack *, NSError *)

Receives each page of the result, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • A nil contentType or date raises NSInvalidArgumentException before any request, because the SDK builds the request parameters with a dictionary literal.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • One call starts an Initial Sync request, GET /v3/stacks/sync, with init=true, the environment of the stack, content_type_uid, and start_from.
  • The SDK sends date in start_from as an ISO 8601 date and time in the time zone of the device. The value ends with the offset from UTC, for example 2026-01-15T09:30:00+0530.
  • While a response includes a pagination_token, the SDK requests the next page and runs the completion block once for each page. On the last page, syncToken contains the sync token. See Sync on the Stack class page.
  • Store the syncToken of the last page, and pass it to the syncToken:completion: method on the next run.

Example

All parameters: sync one content type from last week (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
NSDate *date = [NSDate dateWithTimeIntervalSinceNow:-7 * 24 * 60 * 60];
[stack syncOnly:@"CONTENT_TYPE_UID" from:date completion:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
    if (syncStack.syncToken) {
        // The last page carries the sync token. Store it for the next sync.
        NSLog(@"Sync token: %@", syncStack.syncToken);
    }
}];

All parameters: sync one content type from last week (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let date = Date(timeIntervalSinceNow: -7 * 24 * 60 * 60)
stack.syncOnly("CONTENT_TYPE_UID", from: date) { (syncStack, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
    if let token = syncStack?.syncToken {
        // The last page carries the sync token. Store it for the next sync.
        print("Sync token: \(token)")
    }
}

syncOnly:locale:from:completion:

syncOnly:locale:from:completion: syncs the entries of one content type in one locale, optionally from a given date onward.

NameTypeDescription
contentType (required)NSString *

UID of the content type to sync.

Default: Not applicable
locale (required)NSString *

Locale code to sync, such as en-us.

Default: Not applicable
dateNSDate *

Start date. Omit it to sync from the beginning.

Default: nil
completionBlock (required)void (^)(SyncStack *, NSError *)

Receives each page of the result, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • A nil contentType or locale sends no value for that parameter, so the sync covers every content type or every locale.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • One call starts an Initial Sync request, GET /v3/stacks/sync, with init=true, the environment of the stack, content_type_uid, locale, and start_from when you pass date.
  • The SDK sends date in start_from as an ISO 8601 date and time in the time zone of the device. The value ends with the offset from UTC, for example 2026-01-15T09:30:00+0530.
  • While a response includes a pagination_token, the SDK requests the next page and runs the completion block once for each page. On the last page, syncToken contains the sync token. See Sync on the Stack class page.
  • Store the syncToken of the last page, and pass it to the syncToken:completion: method on the next run.

Example

All parameters: sync one content type in one locale from last week (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
NSDate *date = [NSDate dateWithTimeIntervalSinceNow:-7 * 24 * 60 * 60];
[stack syncOnly:@"CONTENT_TYPE_UID" locale:@"en-us" from:date completion:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
    if (syncStack.syncToken) {
        // The last page carries the sync token. Store it for the next sync.
        NSLog(@"Sync token: %@", syncStack.syncToken);
    }
}];

All parameters: sync one content type in one locale from last week (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let date = Date(timeIntervalSinceNow: -7 * 24 * 60 * 60)
stack.syncOnly("CONTENT_TYPE_UID", locale: "en-us", from: date) { (syncStack, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
    if let token = syncStack?.syncToken {
        // The last page carries the sync token. Store it for the next sync.
        print("Sync token: \(token)")
    }
}

No date: sync one content type in one locale from the beginning (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack syncOnly:@"CONTENT_TYPE_UID" locale:@"en-us" from:nil completion:^(SyncStack *syncStack, NSError *error) {
    if (error) { return; }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
}];

No date: sync one content type in one locale from the beginning (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.syncOnly("CONTENT_TYPE_UID", locale: "en-us", from: nil) { (syncStack, error) in
    guard error == nil else { return }
    print("\(syncStack?.items?.count ?? 0) items on this page")
}

syncOnly:locale:from:publishType:completion:

syncOnly:locale:from:publishType:completion: syncs one type of publish event for one content type in one locale, optionally from a given date onward.

NameTypeDescription
contentType (required)NSString *

UID of the content type to sync.

Default: Not applicable
locale (required)NSString *

Locale code to sync, such as en-us.

Default: Not applicable
dateNSDate *

Start date. Omit it to sync from the beginning.

Default: nil
publishType (required)PublishType

Type of publish event to sync.

Default: Not applicable
completionBlock (required)void (^)(SyncStack *, NSError *)

Receives each page of the result, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • A nil contentType or locale sends no value for that parameter, so the sync covers every content type or every locale.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • One call starts an Initial Sync request, GET /v3/stacks/sync, with init=true and the environment of the stack. It also sends content_type_uid, locale, type, and start_from when you pass date.
  • The SDK sends date in start_from as an ISO 8601 date and time in the time zone of the device. The value ends with the offset from UTC, for example 2026-01-15T09:30:00+0530.
  • The SDK sends the type value that the PublishType page lists for publishType.
  • While a response includes a pagination_token, the SDK requests the next page and runs the completion block once for each page. On the last page, syncToken contains the sync token. See Sync on the Stack class page.
  • Store the syncToken of the last page, and pass it to the syncToken:completion: method on the next run.

Example

All parameters: sync the entries of one content type published in one locale last week (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
NSDate *date = [NSDate dateWithTimeIntervalSinceNow:-7 * 24 * 60 * 60];
[stack syncOnly:@"CONTENT_TYPE_UID" locale:@"en-us" from:date publishType:ENTRY_PUBLISHED completion:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
    if (syncStack.syncToken) {
        // The last page carries the sync token. Store it for the next sync.
        NSLog(@"Sync token: %@", syncStack.syncToken);
    }
}];

All parameters: sync the entries of one content type published in one locale last week (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let date = Date(timeIntervalSinceNow: -7 * 24 * 60 * 60)
stack.syncOnly("CONTENT_TYPE_UID", locale: "en-us", from: date, publishType: .ENTRY_PUBLISHED) { (syncStack, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
    if let token = syncStack?.syncToken {
        // The last page carries the sync token. Store it for the next sync.
        print("Sync token: \(token)")
    }
}

syncPaginationToken:completion:

syncPaginationToken:completion: continues a sync from a pagination token, for example after the network dropped in the middle of a sync.

NameTypeDescription
token (required)NSString *

Pagination token of the page to continue from.

Default: Not applicable
completionBlock (required)void (^)(SyncStack *, NSError *)

Receives each page of the result, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • A nil token raises NSInvalidArgumentException before any request, because the SDK builds the request parameters with a dictionary literal.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • The SDK follows pagination tokens during every sync, so call this method only to resume a sync that stopped.
  • One call sends a Sync using pagination token request, GET /v3/stacks/sync. The SDK sends token in pagination_token, together with init=true and the environment of the stack.
  • When a page after the first fails during a sync, the completion block receives the error and a SyncStack. Its paginationToken contains the token of the page that failed. Pass that token here to resume.
  • While a response includes a pagination_token, the SDK requests the next page and runs the completion block once for each page. On the last page, syncToken contains the sync token. See Sync on the Stack class page.
  • Store the syncToken of the last page, and pass it to the syncToken:completion: method on the next run.

Example

Basic usage: resume a sync from a pagination token (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack syncPaginationToken:@"PAGINATION_TOKEN" completion:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
    if (syncStack.syncToken) {
        // The last page carries the sync token. Store it for the next sync.
        NSLog(@"Sync token: %@", syncStack.syncToken);
    }
}];

Basic usage: resume a sync from a pagination token (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.syncPaginationToken("PAGINATION_TOKEN") { (syncStack, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
    if let token = syncStack?.syncToken {
        // The last page carries the sync token. Store it for the next sync.
        print("Sync token: \(token)")
    }
}

Keep the resume point: read the pagination token when a page fails (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack sync:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        if (syncStack.paginationToken) {
            // The token of the page that failed. Pass it to syncPaginationToken:completion: later to resume.
            NSLog(@"Resume from: %@", syncStack.paginationToken);
        }
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
}];

Keep the resume point: read the pagination token when a page fails (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.sync { (syncStack, error) in
    guard error == nil else {
        if let resumeToken = syncStack?.paginationToken {
            // The token of the page that failed. Pass it to syncPaginationToken later to resume.
            print("Resume from: \(resumeToken)")
        }
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
}

syncPublishType:completion:

syncPublishType:completion: syncs only one type of publish event, such as published entries or deleted assets.

NameTypeDescription
publishType (required)PublishType

Type of publish event to sync.

Default: Not applicable
completionBlock (required)void (^)(SyncStack *, NSError *)

Receives each page of the result, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • One call starts an Initial Sync request, GET /v3/stacks/sync, with init=true, the environment of the stack, and type.
  • The SDK sends the type value that the PublishType page lists for each value, for example entry_published for ENTRY_PUBLISHED.
  • The method takes one value. The API accepts several comma-separated types, but this SDK sends one, so run one sync for each type you need.
  • While a response includes a pagination_token, the SDK requests the next page and runs the completion block once for each page. On the last page, syncToken contains the sync token. See Sync on the Stack class page.
  • Store the syncToken of the last page, and pass it to the syncToken:completion: method on the next run.

Example

Basic usage: sync only deleted entries (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack syncPublishType:ENTRY_DELETED completion:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
    if (syncStack.syncToken) {
        // The last page carries the sync token. Store it for the next sync.
        NSLog(@"Sync token: %@", syncStack.syncToken);
    }
}];

Basic usage: sync only deleted entries (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.syncPublishType(.ENTRY_DELETED) { (syncStack, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
    if let token = syncStack?.syncToken {
        // The last page carries the sync token. Store it for the next sync.
        print("Sync token: \(token)")
    }
}

syncToken:completion:

syncToken:completion: fetches the content published, unpublished, or deleted since the sync that returned the token.

NameTypeDescription
token (required)NSString *

Sync token from the last page of an earlier sync.

Default: Not applicable
completionBlock (required)void (^)(SyncStack *, NSError *)

Receives each page of the result, or the error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation.
  • A nil token raises NSInvalidArgumentException before any request, because the SDK builds the request parameters with a dictionary literal.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • One call sends a Subsequent Sync request, GET /v3/stacks/sync, with sync_token only. It sends no init and no environment.
  • The response lists the changes since the sync that returned token, including deletions.
  • While a response includes a pagination_token, the SDK requests the next page and runs the completion block once for each page. On the last page, syncToken contains the sync token. See Sync on the Stack class page.
  • Store the new syncToken of the last page, and pass it on the next run. Each run starts from the token you pass.

Example

Basic usage: fetch the changes since the last sync (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[stack syncToken:@"SYNC_TOKEN" completion:^(SyncStack *syncStack, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items on this page", (unsigned long)syncStack.items.count);
    if (syncStack.syncToken) {
        // The last page carries the sync token. Store it for the next sync.
        NSLog(@"Sync token: %@", syncStack.syncToken);
    }
}];

Basic usage: fetch the changes since the last sync (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.syncToken("SYNC_TOKEN") { (syncStack, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(syncStack?.items?.count ?? 0) items on this page")
    if let token = syncStack?.syncToken {
        // The last page carries the sync token. Store it for the next sync.
        print("Sync token: \(token)")
    }
}

taxonomy

taxonomy opens the taxonomies of the stack, so you can find the entries tagged with taxonomy terms.

Returns: Taxonomy. A new taxonomy object for this stack.

Validation

  • There is no client-side validation. taxonomy returns no error.
  • Errors come from the find or fetch call that follows, in the error argument of its completion block.

Additional Resource Refer to Delivery API Errors for the full error code list.

Behavior

  • Client-side only. taxonomy makes no request.
  • Each call returns a new Taxonomy that uses the network session and headers of this stack.
  • Next, call the query method of Taxonomy to build a filter on taxonomy terms. Then call the findTaxonomy: method of Query to get the matching entries through Get all entries with defined taxonomies.

Example

Basic usage: find the entries tagged with a term (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack taxonomy] query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@"TERM_UID"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (Entry *entry in [result getResult]) {
        NSLog(@"%@", entry.title);
    }
}];

Basic usage: find the entries tagged with a term (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.taxonomy().query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: "TERM_UID")
query.findTaxonomy { (type, result, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for entry in result?.getResult() ?? [] {
        print(entry.title)
    }
}