Stack
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.
| Name | Type | Description |
|---|---|---|
| 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.
| Name | Type | Description |
|---|---|---|
| headers (required) | NSDictionary<NSString *, NSString *> * | Header names mapped to their values. |
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.
| Name | Type | Description |
|---|---|---|
| uid (required) | NSString * | UID of the asset. |
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.
| Name | Type | Description |
|---|---|---|
| contentTypeName (required) | NSString * | UID of the content type. |
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.
| Name | Type | Description |
|---|---|---|
| params | NSDictionary<NSString *, id> * | Query parameters to add to the request. |
| completionBlock (required) | void (^)(NSArray<NSString *> *, NSError *) | Receives the content types, or the error. |
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.
| Name | Type | Description |
|---|---|---|
| globalFieldName (required) | NSString * | UID of the global field. |
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.
| Name | Type | Description |
|---|---|---|
| url (required) | NSString * | URL of the image asset. |
| params (required) | NSDictionary<NSString *, id> * | Transformation parameter names mapped to their values. |
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.
| Name | Type | Description |
|---|---|---|
| headerKey (required) | NSString * | Name of the header to remove. |
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.
| Name | Type | Description |
|---|---|---|
| headerValue (required) | NSString * | Value of the header. |
| headerKey (required) | NSString * | Name of the header. |
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.
| Name | Type | Description |
|---|---|---|
| completionBlock (required) | void (^)(SyncStack *, NSError *) | Receives each page of the result, or the error. |
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.
| Name | Type | Description |
|---|---|---|
| date (required) | NSDate * | Start date of the content to sync. |
| completionBlock (required) | void (^)(SyncStack *, NSError *) | Receives each page of the result, or the error. |
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.
| Name | Type | Description |
|---|---|---|
| locale (required) | NSString * | Locale code to sync, such as en-us. |
| completionBlock (required) | void (^)(SyncStack *, NSError *) | Receives each page of the result, or the error. |
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.
| Name | Type | Description |
|---|---|---|
| locale (required) | NSString * | Locale code to sync, such as en-us. |
| date (required) | NSDate * | Start date of the content to sync. |
| completionBlock (required) | void (^)(SyncStack *, NSError *) | Receives each page of the result, or the error. |
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.
| Name | Type | Description |
|---|---|---|
| contentType (required) | NSString * | UID of the content type to sync. |
| completionBlock (required) | void (^)(SyncStack *, NSError *) | Receives each page of the result, or the error. |
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.
| Name | Type | Description |
|---|---|---|
| contentType (required) | NSString * | UID of the content type to sync. |
| date (required) | NSDate * | Start date of the content to sync. |
| completionBlock (required) | void (^)(SyncStack *, NSError *) | Receives each page of the result, or the error. |
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.
| Name | Type | Description |
|---|---|---|
| contentType (required) | NSString * | UID of the content type to sync. |
| locale (required) | NSString * | Locale code to sync, such as en-us. |
| date | NSDate * | Start date. Omit it to sync from the beginning. |
| completionBlock (required) | void (^)(SyncStack *, NSError *) | Receives each page of the result, or the error. |
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.
| Name | Type | Description |
|---|---|---|
| contentType (required) | NSString * | UID of the content type to sync. |
| locale (required) | NSString * | Locale code to sync, such as en-us. |
| date | NSDate * | Start date. Omit it to sync from the beginning. |
| publishType (required) | PublishType | Type of publish event to sync. |
| completionBlock (required) | void (^)(SyncStack *, NSError *) | Receives each page of the result, or the error. |
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.
| Name | Type | Description |
|---|---|---|
| token (required) | NSString * | Pagination token of the page to continue from. |
| completionBlock (required) | void (^)(SyncStack *, NSError *) | Receives each page of the result, or the error. |
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.
| Name | Type | Description |
|---|---|---|
| publishType (required) | PublishType | Type of publish event to sync. |
| completionBlock (required) | void (^)(SyncStack *, NSError *) | Receives each page of the result, or the error. |
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.
| Name | Type | Description |
|---|---|---|
| token (required) | NSString * | Sync token from the last page of an earlier sync. |
| completionBlock (required) | void (^)(SyncStack *, NSError *) | Receives each page of the result, or the error. |
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)
}
}