This week, I’ve spent some of my time integrating MailChimp into the client work I’m doing. I found some of the documentation lacking, and there is no example for how to add your email signups to a MailChimp’s list “Group”, so I thought I’d document that here.

(Astute readers who are actually reading from chesstris.com will notice the fact that I’ve got a MailChimp signup form on Chesstris.com also. I haven’t done anything with it, and so far, I’m the only person who has signed up, but it’s there. I’m still sort of trying it out.)

MailChimp has an iOS SDK they call ChimpKit, which is available up on github. In general, it’s a great SDK, but the README has some installation instructions that are both incomplete and also pretty stupid, as far as I’m concerned. After fiddling around with it for a couple of hours yesterday, I’ve concluded that there is no reason to include their sample project as a git submodule of your project. The instructions I’m going to suggest basically don’t do that, so if you are ultra concerned with keeping up to date with the ChimpKit project (keep in mind it hasn’t been updated since 9 months ago), then read-no-further, and go figure out how to actually use the classes in their sample project yourself (since that’s what’s missing from their instructions). Personally, I think git submodules are a PITA, and not worth the effort anyway.

OK, so what you really want to do is the following:

1) Download the ChimpKit code. You can clone it on github, or just download, your preference.

2) ChimpKit requires SBJson, so you’ll need to include that project’s files in your project. You can do this as a git submodule if you really want, but you already know how I feel about those. You can also just add the files to your project and be done with it.

3) Grab just the files in ChimpKit’s “Core” folder and drag them into your project (or use the “Add files…” dialogue). Personally, I like to organize code in my projects in a certain way, so I copied the directory into my project’s “Externals” directory, and renamed it from “Core” to “ChimpKit”.

4) If you don’t care about adding your subscriber to a group, you just need to do the following:

4.a) Add the include: #import "SubscribeAlertView.h" to the top of your view controller or wherever.

4.b) Add this code somewhere, maybe after an IBAction or something.

SubscribeAlertView *alert = [[SubscribeAlertView alloc]
initWithTitle:@"Newsletter Sign-up"
message:@"To sign up for the newsletter please input your email address below."
apiKey:mailChimpAPIKey_
listId:mailChimpListID_
cancelButtonTitle:@"Cancel"
subscribeButtonTitle:@"Confirm"];
[alert show];

Of course you’ll need to define mailChimpAPIKey_ and mailChimpListID_, but both are strings. If you don’t know your list ID, you can find that on the mailchimp website. (Or by using the “lists” api method, and you can see an example of that below.)

…and you’re done!

5) But assuming you care about adding your subscribers to the group, there are two ways you could go. You could modify the code in SubscribeAlertView, or implement the subscribe form yourself. I’m going to assume the former, and not go into the latter, even though it’s what I’m probably going to do since I think their popup looks like toasted a$$.

6) Next we’re going to find your list’s groups. You might be able to skip this step if you already know the name of your grouping and groups, because the API also supports adding by name, but I think this is a better way because a) you can use the ID, and b) you are sure to use the right strings, because you’ll be copy/pasting them out of the JSON. I actually had to perform this step because I’m not the MailChimp admin, I just have access to an API key.

6.a) First, set up the object you’re going to be calling this code from as a <ChimpKitDelegate> in your header, and #import "ChimpKit.h" in the source file.

6.b) Then implement the chimpkit delegate methods:

#pragma mark - chimpkit delegate methods

- (void)ckRequestSucceeded:(ChimpKit *)ckRequest {
NSLog(@"HTTP Status Code: %d", [ckRequest responseStatusCode]);
NSLog(@"Response String: %@", [ckRequest responseString]);
}

- (void)ckRequestFailed:(NSError *)error {
NSLog(@"Response Error: %@", error);
}

6.c) Finally, you’ll need to run the following code to call the MailChimp’s ‘listInterestGroupings‘ API method. Again, you’ll need to define mailChimpListID_. (I just ran this in a ViewController’s viewDidLoad method.)

ChimpKit *ck = [[ChimpKit alloc] initWithDelegate:self
andApiKey:mailChimpAPIKey_];

// get the lists
// [ck callApiMethod:@"lists" withParams:nil];

// get the list groups
NSMutableDictionary *params = [NSMutableDictionary dictionary];
[params setValue:mailChimpListID_ forKey:@"id"];
[ck callApiMethod:@"listInterestGroupings" withParams:params];

(There’s your example in there of how to get the lists.)

With any luck, you’ll get a response that is a big block of JSON. Use your favorite online JSON parser to turn that into something readable, and it’ll probably look something like this:

[
{
"id":9501,
"name":"Web Signups",
"form_field":"hidden",
"display_order":"0",
"groups":[
{
"bit":"1",
"name":"likes chess",
"display_order":"1",
"subscribers":0
},
{
"bit":"2",
"name":"likes go",
"display_order":"2",
"subscribers":0
},
{
"bit":"4",
"name":"likes puzzle games",
"display_order":"3",
"subscribers":0
}]
}
]

7) Add your group subscriptions by modifying SubscribeAlertView.m around line 140 to look like the following:

NSMutableDictionary *params = [NSMutableDictionary dictionary];
[params setValue:self.listId forKey:@"id"];
[params setValue:self.textField.text forKey:@"email_address"];
[params setValue:@"true" forKey:@"double_optin"];
[params setValue:@"true" forKey:@"update_existing"];
NSMutableDictionary *mergeVars = [NSMutableDictionary dictionary];
[mergeVars setValue:
[NSArray arrayWithObjects:
[NSDictionary dictionaryWithObjectsAndKeys:
@"9501", @"id",
@"likes go, likes puzzle games", @"groups",
nil],
nil]
forKey:@"GROUPINGS"];
[params setValue:mergeVars forKey:@"merge_vars"];
[self.chimpKit callApiMethod:@"listSubscribe" withParams:params];

You’ll also note that double_optin was set to false by default. That’s a stupid default, IMHO.

So there you have it. I think you could probably replace the @"9501", @"id" key/value pair with @"Web Signups", @"name", according to the API docs, but I only tried the ID. I also added some code to the SubscribeAlertView‘s requestCompleted:(ChimpKit *)request method to actually let me know that the submission was successful, but other than that, I think I’ve outlined everything pretty well. Let me know if you find this useful.

Oh, and so life happens and it’s July and Oppo-Citrus isn’t out yet. It’s still “right around the corner”, but as you can see I’ve started this exciting (no really!) freelance project. I was definitely hoping this would happen when I set out on my own, and it’s been going great! It’s 20 hours a week of my time, and it turns out that’s actually more than half my time as an indie. (I don’t think it’s because I’m not working 40 hours either, I think there are just hours you end up “losing” to email or twitter or whatever.) Anyway, last week was a holiday week (the boss gave me two days off!), and I’m planning on slacking some this week too, so I haven’t worked on Oppo-Citrus as much as I’ve wanted. The next goal is to get it at least submitted to apple before I leave for vacation the last week of this month. We shall see. We shall see.