Using the Mailchimp Mobile SDK for Android

At a glance

The Mobile Mailchimp SDK allows you to manage Mailchimp contacts from your Android 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 a Mailchimp audience, you'll need to create the Contact object in the Contact Builder. After that's done, you can then pass the contact to the createOrUpdateUser method.

Here’s an example:

val newContact = Contact.Builder("<insert email here>") .setMergeField("FNAME", "Example") .setMergeField("LNAME", "User") .setContactStatus(ContactStatus.SUBSCRIBED) .addTag("Power User") .build() val sdk = Mailchimp.sharedInstance() sdk.createOrUpdateContact(newContact)

Note that if the contact already exists, the information will be updated with the new values.

Update a contact

To update a contact, use the same createOrUpdateContact() method described in the Add a Contact section above.

Update a single contact field

Use any of the following methods to update a single field in the record. Note that they are executed as a separate job.

  • addTag(): Adds a tag to the given user.

  • addTags(): Adds multiple tags to the given user.

  • removeTag(): Removes a tag from the given user.

  • removeTags(): Removes multiple tags from the given user.

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

  • setMarketingPermission(): Sets the status of a marketing permission for a contact.

Update multiple contact fields

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

Use Job Status and Work Manager

 The Mailchimp SDK uses Google’s Work Manager 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 using the getStatusById() and getStatusByIdLiveData() methods. getStatusById() returns the current status of a job.

Here’s an example.

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

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

Here’s an example.

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

Contact schema

The Contact schema is as follows.

Email

The Email Address is the unique identifier for each contact and is required for every interaction with the SDK.

Tags

Using the SDK, you can apply or remove tags from contacts. Each tag is identified using a string, and if the tag has not been previously used in your account, it will be created.

Autotagging

If autotagging is enabled in the MailchimpSdkConfiguration, all created or updated contacts are automatically tagged with AndroidPhone or Tablet.

Merge Fields

Merge fields are the set of key value pairs you can set for each contact and customize for each audience. Common examples of merge fields are first name, last name, and phone number. Note that merge fields key off of a capitalized string. The key does not include vertical bars on either end (ex. FNAME, not |FNAME|).

Here are a few things to know.

  • Go to the Audience Settings page in the mailchimp app to locate your merge fields. They are also listed after the SDK key is created.

  • On the Audience Settings page, you can also mark them as required. If you attempt to create a contact without setting the required merge fields, the creation will silently fail.

String Merge Fields

Most 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 not represented as a string. Instead, the receive a custom object that follows the builder pattern. Addresses have three required fields, Address Line One, City, and Zip.

There are also three optional fields, Address Line Two, State, and Country.

Here is an example of an address object.

val address = Address.Builder("404 Main St.", Atlanta, "30308") .setAddressLineTwo("apt. 101") .setState("Georgia") .setCountry(Country.USA) .build()

Collect contact events

Adding an event

To associate an event with a contact, pass the email, event name, and properties (optional) into the addContactEvent method. This adds the event to the contact.

Unlike adding or updating contact information, event requests execute immediately and will not be reattempted if they fail.

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

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

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

Properties are passed into the request as a Map<String, String>, the former being the name and the latter being the value.

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.

Marketing Permissions

GDPR compliant audiences require users to consent individually to email, direct mail, and customized online advertising.

The Mailchimp SDK supports updating these permissions by supplying the audience-specific keys to the contact when they are created or updated.

You can mark permissions as granted or denied. Simply setting these permissions will not make your audience GDPR compliant.

See the Mailchimp GDPR Tutorial for a more complete description of Marketing Permissions and how to use them.

val emailPermissionKey = "1234567890" // Example Key val mailPermissionKey = "2345678901" // Example Key val advertisingPermissionKey = "3456789012" val newContact = Contact.Builder("example@email.com") .setMarketingPermission(emailPermissionKey, true) .setMarketingPermission(mailPermissionKey, true) .setMarketingPermission(advertisingPermissionKey, true) .build() val sdk = Mailchimp.sharedInstance() sdk.createOrUpdateContact(newContact)

Use the demo app

Autofill demo SDK Key (Optional)

  1. On a Unix-like OS, in your home (~) folder, go into the .gradle folder and open or create a gradle.properties file.

  2. Add the following key-value pair to have your SDK Key for the demo app filled in automatically. Replace with the SDK Key you want to use.

MAILCHIMP_SDK_DEMO_KEY=<YOUR_SDK_KEY>