Using the Mailchimp Mobile SDK for iOS

At a glance

The Mobile Mailchimp SDK for iOS allows you to manage Mailchimp contacts from your iOS app.

In this article, you'll learn how to add and update contact information, add tags, configure merge fields, and set marketing permissions.

Add a contact

To add a contact to an audience (along with merge fields and/or tags), first instantiate a new Contact struct. Then, pass it to the createOrUpdate() method.

If the contact already exists, the information is updated with the new values.

Here’s an example.

var contact: Contact = Contact(emailAddress: "example@email.com") let mergeFields = ["FNAME": MergeFieldValue.string("Example"), "LNAME": MergeFieldValue.string("User")] contact.mergeFields = mergeFields contact.tags = [Contact.Tag(name: "mobile-signup", status: .active)] MailchimpSDK.createOrUpdate(contact: contact) { result in switch result { case .success: print("Successfully added or updated contact") case .failure(let error): print("Error: \(error.localizedDescription)") } }

Update a contact

To update a contact, use the createOrUpdate() method described above.

Update a single contact field

Use these methods to update a single contact field. Note that they are executed as separate network requests.

  • addTag(): Adds one tag to a contact.

  • addTags(): Adds multiple tags to a contact

  • removeTag(): Removes a tag from a contact.

  • removeTags(): Removes multiple tags from a contact.

  • setMergeField(): Sets or updates the merge field for a contact.

Update multiple contact fields

To update multiple contact fields simultaneously, use the createOrUpdate() method.

Add or remove tags

Use the example below to add or remove tags.

MailchimpSDK.addTag(name: tagName, emailAddress: "example@email.com") { result in switch result { case .success: print("Successfully added tag: \(tagName)") case .failure(let error): print("Error: \(error.localizedDescription)") } } MailchimpSDK.removeTag(name: tagName, emailAddress: "example@email.com") { result in switch result { case .success: print("Successfully removed tag: \(tagName)") case .failure(let error): print("Error: \(error.localizedDescription)") } }

To learn more about how tagging works in Mailchimp, see Organize Contacts with Tags.

Set merge fields

To set merge fields, use this example. Refer to Manage Audience and Signup Form Fields for a more detailed feature explanation.

MailchimpSDK.setMergeField(emailAddress: "example@email.com", name: fieldName, value: fieldValue) { result in switch result { case .success: print("Successfully added merge field: \(fieldName), \(fieldValue)") case .failure(let error): print("Error: \(error.localizedDescription)") } }

Contact schema

The Contact schema is as follows.

Email

The Email Address is the unique identifier for each contact in an audience. An email address is required for every interaction with the SDK.

Tags

Users can add or remove tags from their contact information. Each tag is identified using a String. If a tag has not been previously used in your account, it will be created.

Autotagging

If autotagging is enabled, all new or updated contacts are automatically tagged with iOS and either Phone or Tablet.

Merge Fields

Merge fields are key value pairs that can be set on each contact and can be customized for each audience. Common examples of merge fields are first name, last name, and phone number.

Here are a few additional things to know:

  • The value of a merge field can be set and updated from the SDK. Merge fields are keyed off of a capitalized string.

  • The Key does not include vertical bars on either end (ex. FNAME and not |FNAME|).

Note that Merge Fields can be marked as required on the Audience Settings page in your Mailchimp account. If you attempt to create a contact without setting the required merge fields, the request will silently fail.

String Merge Fields

The majority of merge field types are represented as a String. This includes Text, Number, Radio Buttons, Drop Downs, Dates, Birthday, Phone Numbers, and Websites.

Address Merge Fields

Address Merge Fields are represented as an Address struct. Addresses have three required fields, Address Line One, City, and Zip. In addition, there are three optional fields, Address Line Two, State, and Country.

Here is an example of an Address object.

let address = Address(addressLineOne: "123 Chimp St.", addressLineTwo: "Suite 456", city: "Atlanta", state: "GA", zipCode: "30308", country: CountryCode.USA)

Note: Merge Fields can be marked as required on the Audience Settings page in your Mailchimp account. If you attempt to create a contact without setting the required merge fields, the request will silently fail.

Set the contact status

The Contact Status indicates the type of communication the user has consented to receive. The status can either be Subscribed (receives general marketing campaigns) or Transactional (only receives transactional emails). This value is set when the contact is created and can't be changed. If changed, the new value is ignored. By default, all users are marked as Transactional if this value is not set at the time the contact was created.

Add a contact event

To associate an event with a contact, first instantiate a new Event struct. Then, pass the event to the trackEventWithAttributes() method.

Here’s an example.

let event: Event = try! Event(emailAddress: "example@email.com", name: "signup", properties: ["source": "iOS"]) MailchimpSDK.trackEventWithAttributes(event: event) { result in switch result { case .success: print("Successfully tracked an event") case .failure(let error): print("Error: \(error.localizedDescription)") } }

Event schema

The Event schema is as follows.

Email

The Email Address is the unique identifier for each contact in an audience. An email address is required for every interaction with the SDK.

Name

Each event is identified using a String. The maximum length of an event name is 30 characters.

Properties

Properties can be associated with any event. These properties have a String key and String value. Property names are limited to A-Z and underscores.

Set marketing permissions

Before you can communicate with any contact with GDPR-enabled fields, you must first set the appropriate marketing permissions. These fields indicate how a contact wants their information to be used (e.g., direct mail or customized online advertising).

If the user granted permission, instantiate a MarketingPermission struct with the corresponding marketingPermissionsId and setting enabled.

Here's an example.

let permission1 = Contact.MarketingPermission(marketingPermissionId: "permission1", enabled: true)