{"id":20791712,"url":"https://github.com/mailchimp/mailchimp-sdk-ios","last_synced_at":"2025-06-23T16:33:57.834Z","repository":{"id":41293793,"uuid":"216649833","full_name":"mailchimp/Mailchimp-SDK-iOS","owner":"mailchimp","description":null,"archived":false,"fork":false,"pushed_at":"2024-03-12T06:56:25.000Z","size":6862,"stargazers_count":12,"open_issues_count":2,"forks_count":22,"subscribers_count":21,"default_branch":"main","last_synced_at":"2024-04-26T14:42:56.943Z","etag":null,"topics":["ios-sdk","mailchimp","mailchimp-sdk","sdk","sdk-ios","swift"],"latest_commit_sha":null,"homepage":"https://mailchimp.com/developer/guides/mobile-sdk/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mailchimp.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-21T19:33:18.000Z","updated_at":"2024-06-21T13:00:52.759Z","dependencies_parsed_at":"2024-06-21T13:00:48.745Z","dependency_job_id":"2abea666-8298-45bc-bc30-eccfb2a4d30d","html_url":"https://github.com/mailchimp/Mailchimp-SDK-iOS","commit_stats":{"total_commits":83,"total_committers":14,"mean_commits":5.928571428571429,"dds":0.6385542168674698,"last_synced_commit":"fe8fac3aff0e373fa6f3ad54b3330a8f16e20073"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailchimp%2FMailchimp-SDK-iOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailchimp%2FMailchimp-SDK-iOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailchimp%2FMailchimp-SDK-iOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailchimp%2FMailchimp-SDK-iOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mailchimp","download_url":"https://codeload.github.com/mailchimp/Mailchimp-SDK-iOS/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225059347,"owners_count":17414674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ios-sdk","mailchimp","mailchimp-sdk","sdk","sdk-ios","swift"],"created_at":"2024-11-17T15:46:56.005Z","updated_at":"2024-11-17T15:46:56.596Z","avatar_url":"https://github.com/mailchimp.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://mailchimp.com/developer/\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/mailchimp/mailchimp-client-lib-codegen/master/resources/images/mcdev-banner.png\" alt=\"Mailchimp Developer\" width=\"100%\" height=\"auto\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# MailchimpSDK-iOS\n\n##### Table of Contents  \n[Getting Started](#getting-started)  \n[Installation](#installation)  \n[Initializing the SDK](#initializing-the-sdk)  \n[Collecting contact information](#collecting-contact-information)  \n[Contact Schema](#contact-schema)  \n[Collecting contact events](#collecting-contact-events)  \n[Event Schema](#event-schema)\n\n## Getting Started\n\n### Requirements\n\n* Deployment target iOS 12.0 or above\n* Xcode version 11 or above\n* Ruby 2.4 or above (for fastlane)\n\n### Retrieving SDK Key\n\n* See the [Mailchimp SDK documentation](https://mailchimp.com/developer/guides/mobile-sdk-ios/#Step_1._Retrieve_the_SDK_Key) for details on retrieving the key.\n\n## Installation\n### Option 1: Cocoapods\nFor the latest version of our SDK, add the following to your project's Podfile:\n```\npod 'MailchimpSDK'\n```\n\n### Option 2: Manual\n1. Clone this repository\n2. Run `bundle exec fastlane create_binary_framework` to build the Swift binary framework for iOS and iOS Simulator.\n3. Add the XCFramework:\n\n  Click on the Project navigator, select your app’s target, go to the General tab, scroll down to Frameworks, Libraries, and Embedded Content. Drag the Mailchimp.xcframework from this repo into this section.\n\n  ![Drag the framework into Frameworks, Libraries, and Embedded Content](https://user-images.githubusercontent.com/42216769/69161161-8f641480-0a9f-11ea-93ec-5599aac85423.gif)\n  \n  ### Option 3: Swift Package Manager\n  To use Swift Package Manager, in Xcode, click File -\u003e Swift Packages -\u003e Add Package Dependency, enter MailchimpSDK repo's URL or you can log into Xcode with your GitHub account and just type MailchimpSDK to search.\n\n\n## Initializing the SDK\n\nThe initialize method has three different fields.\n\n* SDK Key (Required): The SDK key gives you access to your audience.\n* Debug Mode (Optional): Debug Mode enables additional debug only functionality such as extra logging. This is off by default.\n* Auto Tagging (Optional): Auto Tagging automatically tags contacts with information such as Device Type and Platform. This is on by default.\n\n```swift\nMailchimp.initialize(token: sdkKey)\n```\n\n## Collecting contact information\n\n### Adding A Contact\n\nTo add a contact to your Mailchimp audience, first instantiate a new Contact struct. Then pass the contact into the `createOrUpdate()` method. This will add the contact to your Mailchimp audience with applied merge fields and/or tags. If the contact already exists, their information will be updated with the values that were passed in.\n\n```swift\nvar contact: Contact = Contact(emailAddress: \"example@email.com\")\nlet mergeFields = [\"FNAME\": MergeFieldValue.string(\"Example\"),\n                   \"LNAME\": MergeFieldValue.string(\"User\")]\ncontact.status = .subscribed\ncontact.mergeFields = mergeFields\ncontact.tags = [Contact.Tag(name: \"mobile-signup\", status: .active)]\nMailchimp.createOrUpdate(contact: contact) { result in\n    switch result {\n    case .success:\n        print(\"Successfully added or updated contact\")\n    case .failure(let error):\n        print(\"Error: \\(error.localizedDescription)\")\n    }\n}\n```\n\n### Updating a Contact\n\nYou may update a contact by using the same `createOrUpdate()` method described in the Adding a Contact section.\n\nIn addition to updating a whole contact, we provide a number of methods to update a single fields on a contact. These are executed as separate network requests. To update multiple fields at once, use the `createOrUpdate()` method.\n\nSingle field update methods include\n\n* `addTag()`: Adds a tag to the given user.\n* `addTags()`: Adds multiple tags to the given user.\n* `removeTag()`: Removes a tag from the given user.\n* `removeTags()`: Removes multiple tags from the given user.\n* `setMergeField()`: Sets or updates the merge field for a given user.\n\n### Add/Remove Tags\n\n```swift\nMailchimp.addTag(name: tagName,\n                   emailAddress: \"example@email.com\") { result in\n                   switch result {\n                   case .success:\n                       print(\"Successfully added tag: \\(tagName)\")\n                   case .failure(let error):\n                       print(\"Error: \\(error.localizedDescription)\")\n                   }\n               }\n\nMailchimp.removeTag(name: tagName,\n                      emailAddress: \"example@email.com\") { result in\n                      switch result {\n                      case .success:\n                         print(\"Successfully removed tag: \\(tagName)\")\n                      case .failure(let error):\n                         print(\"Error: \\(error.localizedDescription)\")\n                      }\n               }\n```\n\n### Set Merge Fields\n\n```swift\nMailchimp.setMergeField(emailAddress: \"example@email.com\",\n                          name: fieldName,\n                          value: fieldValue) { result in\n                          switch result {\n                          case .success:\n                               print(\"Successfully added merge field: \\(fieldName), \\(fieldValue)\")\n                          case .failure(let error):\n                               print(\"Error: \\(error.localizedDescription)\")\n                          }\n               }\n```\n## Contact Schema\n\n### Email\n\nThe Email Address is the unique identifier for each contact in an audience. An email address is required for every interaction with the SDK.\n\n### Tags\n\nUsers can add or remove tags from their contact information. Each tag is identified using a String. If a tag has not been previously used on your account, it will be created.\n\n#### Autotagging\n\nIf autotagging is enabled, all created or updated contacts will be automatically tagged with `iOS` and either `Phone` or `Tablet`.\n\n### Merge Fields\n\nMerge fields are key value pairs that can be set on each contact. They can be customized for each audience. Common examples of merge fields are first name, last name, and phone number.\nThe 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|).\n\nWhile Merge Fields can be marked as required on the audience settings, those requirements will not be enforced when using the Mailchimp SDK.\n\n#### String Merge Fields\nThe majority of merge field types are represented as a String. This includes Text, Number, Radio Buttons, Drop Downs, Dates, Birthday, Phone Numbers, and Websites.\n\n#### Address Merge Fields\n\nMerge Fields of type address are represented as an Address struct. Addresses have three required fields, Address Line One, City, and Zip.\nIn addition there are three optional fields, Address Line Two, State, and Country. Below is an example of an Address object.\n\n```swift\nlet address = Address(addressLineOne: \"123 Chimp St.\",\n                      addressLineTwo: \"Suite 456\",\n                      city: \"Atlanta\",\n                      state: \"GA\",\n                      zipCode: \"30308\",\n                      country: CountryCode.USA)\n```\n\n### Contact Status\n\nThe Contact Status represents what type of communication the user has consented to. This can either be Subscribed (will receive general marketing campaigns) or Transactional (will only receive transactional emails).\nThis value can only be set when the contact is created. If this is set at any other time, the new value will be ignored. By default all users will be marked as transactional if this value is not set at creation.\n\nYou can subscribe a new contact to general marketing campaigns by setting `status`.\n\n```swift\ncontact.status = .subscribed\n```\n\n### Marketing Permissions\n\nAppropriate marketing permissions need to be set to communicate with any contact/s added to an audience with GDPR enabled fields. These fields specify how a contact would like their information to be used (ex: for direct mail or for customized online advertising).\n\nMarketing permissions are set by instantiating a MarketingPermission struct with the corresponding `marketingPermissionsId` and setting `enabled` if the user granted permission for that permission ID.\n\n```swift\nlet permission1 = Contact.MarketingPermission(marketingPermissionId: \"permission1\", enabled: true)\n```\n\n## Collecting contact events\n\n### Adding an event\n\nTo add an event associated with a contact, first instantiate a new Event struct. Then pass the event into the `trackEventWithAttributes()` method. This will add the event to the specified contact.\n\n```swift\nlet event: Event = try! Event(emailAddress: \"example@email.com\", name: \"signup\", properties: [\"source\": \"iOS\"])\nMailchimp.trackEventWithAttributes(event: event) { result in\n    switch result {\n    case .success:\n        print(\"Successfully tracked an event\")\n    case .failure(let error):\n        print(\"Error: \\(error.localizedDescription)\")\n    }\n}\n```\n\n## Event Schema\n\n### Email\n\nThe Email Address is the unique identifier for each contact in an audience. An email address is required for every interaction with the SDK.\n\n### Name\n\nEach event is identified using a String. The maximum length of an event name is 30 characters.\n\n### Properties\n\nAny 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.\n\n## FAQ\n\nDo you have an Android version?\n\u003eYes! You can find it [here](https://github.com/mailchimp/Mailchimp-SDK-Android)\n\nWhy is the SDK throwing an error when I try to create a contact?\n\u003eCheck that you are initializing the SDK with the correct token format. The token includes the `-us` suffix.\n\nWhy do calls silently fail?\n\u003eFor security, our SDK is write-only. Contact data cannot be retrieved via the SDK. Calls fail silently so that contact data cannot be deduced from error messages. (e.g. If adding a contact failed loudly, one could deduce that the contact exists on your list.)\n\nHow do I use the SDK in my Objective-C project?\n\u003eThe 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.\n\nDoes the Mailchimp mobile SDK track my users?\n\u003eThe Mailchimp mobile SDK does not track your users. The Mailchimp mobile SDK automatically adds your mobile application users to your Mailchimp audience so that you can send them marketing communications. Mailchimp does not provide information about your app’s users to data brokers. The mobile SDK does not combine user data from your app with information from other apps in order to place targeted advertisements. For more information regarding Mailchimp’s mobile SDK, please click [here](https://mailchimp.com/help/mobile-sdk/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailchimp%2Fmailchimp-sdk-ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmailchimp%2Fmailchimp-sdk-ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailchimp%2Fmailchimp-sdk-ios/lists"}