Mobile SDK

The Mailchimp Mobile SDK implements a mobile-oriented subset of Mailchimp’s Marketing API, giving iOS and Android developers an easier path to integrating with core functionality most relevant to mobile devices. 

This documentation covers how to install and initialize the SDK for both platforms, as well as its major features for working with contacts and events. To walk through using the Mobile SDK with an example customer, see the Manage Contacts and Events with the Mobile SDK guide.

Write-only feature set

The Mobile SDK allows for creating contacts and updating their data—including tags, merge fields, and GDPR permissions. It can also log events based on in-app behavior of mobile users.

For security purposes, the Mobile SDK is write-only. For additional security, calls to create or update contacts fail silently—otherwise bad actors could try to determine who is or is not in your list from error messages alone.

To retrieve contact data that you have created with the Mobile SDK, use the Lists/Audiences endpoints in the Mailchimp Marketing API or the All contacts page for your audience in the Mailchimp application.

Mobile SDK keys

While the Marketing API has one key for each API user, the Mobile SDK has different keys for each of your audiences. To obtain the key for a particular audience:

1. Go to the API Keys section of your Mailchimp account and scroll down to Your Mobile SDK Client keys.

2. Click Create New Key.

3. Select an audience and then label your key with a descriptive name.

4. Read and accept the terms and license agreement for the Mobile SDK.

5. Click Create Key. Copy your key and store it in a secure location. You won’t be able to see or copy the full key on the Account page once it’s been generated.

Even though the Mobile SDK key does not provide access to the Mailchimp Marketing API, you should still consider your key private and keep it safe.

To add the Mobile SDK to your iOS app, you’ll need:

• Xcode version 11 or above

• Deployment target of iOS 12.0 or above

• Ruby 2.4 or above (for fastlane)

Cocoapods installation

If you use the Cocoapods dependency manager, simply add the following line to your project’s Podfile:

pod 'MailchimpSDK'

Manual installation

To install the Mailchimp Mobile SDK manually:

1. Clone the Mailchimp SDK iOS GitHub repository.

2. Run bundle exec fastlane create_binary_framework to build the Swift binary framework for iOS and the iOS Simulator.

3. In Xcode, click on the Project Navigator, select your app’s target, go to the General tab, scroll down to Frameworks, Libraries, and Embedded Content. 

4. Drag Mailchimp.xcframework from your clone of the SDK repository into this section, or click the + button and select it in the Open dialog.

To add the Mobile SDK to your Android app, you’ll need Android API Level 21 (5.0) or above.

To install:

1. Add https://jitpack.io to your list of maven repositories if it’s not already present.

2. Add the Mailchimp Mobile SDK to your list of dependencies.

repositories { 
// any other repositories
maven { url 'https://jitpack.io' }
}
dependencies { 
implementation 'com.github.mailchimp:Mailchimp-SDK-Android:1.0.0'
}

We recommend that you initialize the SDK when your app starts. The initialization process configures three fields:

• SDK Key (Required): The SDK key gives you access to your audience.

• Debug Mode (Optional): Debug Mode enables additional debug-only functionality like extra logging. This mode is off by default.

• Auto-Tagging (Optional): If enabled, all created or updated contacts will be automatically tagged with their platform (iOS or Android) and device type (Phone or Tablet). This feature is on by default.

val sdkKey = "YOUR_API_KEY"
val isDebugBuild = BuildConfig.DEBUG 
val configuration = MailchimpSdkConfiguration.Builder(context, sdkKey)
	.isDebugModeEnabled(isDebugBuild) 
	.isAutoTaggingEnabled(true) 
	.build() 
val mailchimpSdk = Mailchimp.initialize(configuration) // creates a new shared instance that can be accessed by calling Mailchimp.sharedInstance()

The Mobile SDK provides several methods for creating and updating contact data, including email address, names, merge fields, and GDPR permissions. When working with contacts, the email address is the unique identifier for each contact in an audience and it is required for every interaction with the SDK.

Add a contact

To add a contact to your Mailchimp audience, specify the contact’s email address and any additional information, such as tags or merge fields. If you attempt to create a contact that already exists, the contact’s information will be updated with the newly specified values.

val newContact = Contact.Builder("example@email.com")
       .setMergeField("FNAME", "Example")
       .setMergeField("LNAME", "User")
       .setContactStatus(ContactStatus.SUBSCRIBED)
       .addTag("Power User")
       .build()
val sdk = Mailchimp.sharedInstance()
sdk.createOrUpdateContact(newContact)

Update a contact

You can update multiple fields on a contact, using the same method as for adding contacts. In addition to updating a whole contact, Mailchimp provides a number of methods to update a single contact field. These are executed as separate network requests. 

Single-field update methods include:

Merge fields and addresses

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

Merge field keys are an all-caps string and do not include vertical bar characters (e.g., FNAME, not |FNAME|). Merge field values are strings, except for address values. 

Addresses have internal structure with three required fields (Address Line One, City, and Zip) and three optional fields (Address Line Two, State, and Country).

val address = Address.Builder("123 Chimp St.", “Atlanta”, "30308")
         .setAddressLineTwo("Suite 456")
         .setState("GA")
         .setCountry(Country.USA)
         .build()

GDPR permissions

GDPR-compliant audiences require each user to consent to receiving email, direct mail, and customized online advertising. These permissions are represented as a combination of an audience-specific key and a boolean value, with true indicating consent. 

val emailPermissionKey = "YOUR_AUDIENCE_EMAIL_KEY"
val mailPermissionKey = "YOUR_AUDIENCE_MAIL_KEY"
val advertisingPermissionKey = "YOUR_AUDIENCE_ADVERTISING_KEY"
val newContact = Contact.Builder("example@email.com")
	   .setMarketingPermission(emailPermissionKey, true)
	   .setMarketingPermission(mailPermissionKey, true)
	   .setMarketingPermission(advertisingPermissionKey, true)
	   .build()
val sdk = Mailchimp.sharedInstance()
sdk.createOrUpdateContact(newContact)

Contact schema

The following fields are available on all contacts. Only the email field is required by default. Depending on your configuration, certain merge fields may also be required.

To associate an event with a contact, specify the contact’s email address, event name, and optionally any properties of the event.

val mailchimpSdk = Mailchimp.sharedInstance()
val eventProperties = mapOf("item_id" to "12894309543")
mailchimpSdk.addContactEvent("example@email.com", "User Browsed Item", eventProperties)

Event schema

The following fields are available on events. The email field associates the event with the corresponding contact.

The Mailchimp Mobile SDK uses Google’s WorkManager to manage retry logic and job execution order. This means that all operations are guaranteed to execute regardless of network status and app restart. The order of execution is also maintained so multiple calls execute in the correct order.

For most cases, a “fire and forget” approach is sufficient. If needed, you can poll the status of jobs. 

The getStatusById() method returns the current status of a job:

val uuid = sdk.addTag("example@user.com", "ExampleTag") 
val status = sdk.getStatusById(uuid) 
//... 
if (status == WorkStatus.FINISHED) { 
	Log.i("Mailchimp SDK", "Tag Was Added")
}

The getStatusByIdLiveData() method returns LiveData that can be used to monitor the state of a job:

val uuid = sdk.addTag("example@user.com", "ExampleTag") 
val statusLiveData = sdk.getStatusByIdLiveData(uuid) statusLiveData.observe( 
this 
	Observer { 
		Toast.makeText(this, "Current Job Status: $it", 	Toast.LENGTH_SHORT).show() 
	}
)

The iOS version of the Mobile SDK is designed to be used in Swift projects. The best way to interact with an Objective-C project is to create a Swift wrapper object that can initialize the SDK and create a contact for you.

Apple requires developers to answer questions about their apps’ privacy when submitting to App Store Connect. The following information may help you answer these questions:

• The Mailchimp Mobile SDK does not track your users. 

• Mailchimp does not provide information about your app’s users to data brokers. 

• The Mailchimp Mobile SDK does not combine user data from your app with information from other apps in order to place targeted advertisements.