{"id":20791700,"url":"https://github.com/mailchimp/mailchimp-sdk-android","last_synced_at":"2025-05-05T21:24:00.281Z","repository":{"id":48740408,"uuid":"216649935","full_name":"mailchimp/Mailchimp-SDK-Android","owner":"mailchimp","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-23T18:14:34.000Z","size":349,"stargazers_count":21,"open_issues_count":0,"forks_count":18,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-23T19:28:28.655Z","etag":null,"topics":["android-sdk","kotlin","mailchimp","mailchimp-sdk","sdk","sdk-android"],"latest_commit_sha":null,"homepage":"https://mailchimp.com/developer/guides/mobile-sdk/","language":"Kotlin","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,"zenodo":null}},"created_at":"2019-10-21T19:33:45.000Z","updated_at":"2025-04-23T18:12:31.000Z","dependencies_parsed_at":"2024-11-17T15:48:07.623Z","dependency_job_id":"2fddaade-5d76-4eac-aeff-5c4006267983","html_url":"https://github.com/mailchimp/Mailchimp-SDK-Android","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailchimp%2FMailchimp-SDK-Android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailchimp%2FMailchimp-SDK-Android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailchimp%2FMailchimp-SDK-Android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailchimp%2FMailchimp-SDK-Android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mailchimp","download_url":"https://codeload.github.com/mailchimp/Mailchimp-SDK-Android/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252577529,"owners_count":21770818,"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":["android-sdk","kotlin","mailchimp","mailchimp-sdk","sdk","sdk-android"],"created_at":"2024-11-17T15:46:51.584Z","updated_at":"2025-05-05T21:24:00.233Z","avatar_url":"https://github.com/mailchimp.png","language":"Kotlin","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# Mailchimp Android SDK\n\nCreate and update your Mailchimp contacts from your Android app. The Mailchimp SDK allows you to,\n* Add new users straight to your audience\n* Update your contacts based on user action\n* Add relevant tags to contacts\n* Set or update merge fields\n\n## Getting Started\n\n### Requirements\n\n* Android API Level 21 (5.0) and above\n\n### Retrieving SDK Key\n\nSee the [Mailchimp SDK documentation](https://mailchimp.com/developer/guides/mobile-sdk-android/#Step_1._Retrieve_the_SDK_Key) for details on retrieving a key.\n\n### Adding The Mailchimp SDK to your Project\n\nFirst, add https://jitpack.io to your list of maven repositories if it's not already present. Ex. This is an list of Gradle repositories that contains jitpack\n\n```gradle\nrepositories {\n    mavenCentral()\n    maven { url 'https://jitpack.io' } // \u003c-- New repository\n}\n```\n\nNext add the Mailchimp SDK to your list of dependencies. Below is a gradle example\n\n```gradle\nimplementation 'com.github.mailchimp:Mailchimp-SDK-Android:1.1.0'\n```\n\n### Initializing the SDK\n\nThe first step is to create the configuration object. The configuration object has three different fields.\n\n* SDK Key (Required): The SDK key gives you access to your audience. More details can be found in the previous section.\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\nBelow is an example of a potential configuration.\n\n```kotlin\n    val sdkKey = \"12345678901234567890123456789012-us12\" //Example SDK Key\n    val isDebugBuild = BuildConfig.DEBUG\n    val configuration = MailchimpSdkConfiguration.Builder(context, sdkKey)\n        .isDebugModeEnabled(isDebugBuild)\n        .isAutoTaggingEnabled(true)\n        .build()\n```\n\nOnce you have the configuration object setup, simply call the initialize method.\n\n```kotlin\n    val mailchimpSdk = Mailchimp.initialize(configuration)\n```\n\nThis initialize the SDK and returns the new shared instance. It is recommended you initialize on app start.\nSubsequently the Shared Instance can be accessed by calling ```Mailchimp.sharedInstance()```.\n\n## Usage\n\n### Adding A Contact\n\nTo add a contact to your Mailchimp audience, first create the Contact object using the Contact Builder. Once created pass the user in to the\ncreateOrUpdateUser method. This will add the contact to your Mailchimp audience. If the contact already exists, their information will be updated\nwith the values that were passed in.\n\n```kotlin\n    val newContact = Contact.Builder(\"\u003cinsert email here\u003e\")\n           .setMergeField(\"FNAME\", \"Example\")\n           .setMergeField(\"LNAME\", \"User\")\n           .setContactStatus(ContactStatus.SUBSCRIBED)\n           .addTag(\"Power User\")\n           .build()\n    val sdk = Mailchimp.sharedInstance()\n    sdk.createOrUpdateContact(newContact)\n```\n\n### Updating a Contact\n\nYou may update a contact by using the same `createOrUpdateContact()` method described in the Adding a Contact section.\n\nIn addition to updating a whole contact, we provided a number of methods to update a single field on a contact. These will be executed as a separate job.\nSo if you wish to update multiple fields at once, we suggest using the `createOrUpdateContact()` 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* `setMarketingPermission()`: Sets the status of a marketing permission for a given user.\n\n\n### Job Status and Work Manager\n\nThe Mailchimp SDK uses [Google's Work Manager](https://developer.android.com/reference/androidx/work/WorkManager) to manage retry logic and job execution order.\nThis means that all operations guaranteed to execute regardless of network status and App Restart. In addition the order of execution is maintained so that multiple calls\nwill execute in the correct order.\n\nFor most use cases a fire and forget approach will be sufficient. However if needed, you can poll the status of jobs using the `getStatusById()` and `getStatusByIdLiveData()` methods.\n\n`getStatusById()` will return the current status of a job.\n\n```kotlin\nval uuid = sdk.addTag(\"example@user.com\", \"ExampleTag\")\nval status = sdk.getStatusById(uuid)\n//...\nif (status == WorkStatus.FINISHED) {\n    Log.i(\"Mailchimp SDK\", \"Tag Was Added\")\n}\n```\n\n`getStatusByIdLiveData()` will return a [LiveData](https://developer.android.com/topic/libraries/architecture/livedata) that may be used to monitor the state of a job.\n\n```kotlin\nval uuid = sdk.addTag(\"example@user.com\", \"ExampleTag\")\nval statusLiveData = sdk.getStatusByIdLiveData(uuid)\nstatusLiveData.observe(\n            this\n            Observer {\n                Toast.makeText(this, \"Current Job Status: $it\", Toast.LENGTH_SHORT).show()\n            })\n```\n\n## Contact Schema\n\n### Email\n\nThe Email Address is used as the unique identifier for each contact in an audience. An email address will be required for every interaction with the SDK.\n\n### Tags\n\nUsing the SDK, users can have tags applied or removed to their contact information. Each tag is identified using a String. If tag has not been previously used on your account, it will be created.\n\n#### Autotagging\n\nIf autotagging is enabled in the `MailchimpSdkConfiguration`, all created or updated contacts will be automatically tagged with `Android` and either `Phone` or `Tablet`.\n\n### Merge Fields\n\nMerge fields are a set of key value pairs that can be set on each contact. They can be customized for each audience. Common examples of merge fields would be 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\n* Merge fields can be located on audience settings page on the mailchimp website and are also listed out after sdk-key creation.\n* While 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 not represented as a string and instead receive a custom object that follows the builder pattern. 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```kotlin\n    val address = Address.Builder(\"404 Main St.\", \"Atlanta\", \"30308\")\n            .setAddressLineTwo(\"apt. 101\")\n            .setState(\"Georgia\")\n            .setCountry(Country.USA)\n            .build()\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\n### Marketing Permissions\n\nGDPR compliant audiences require users to consent individually to Email, Direct Mail, and Customized Online Advertising.\nThe Mailchimp SDK supports updating these permissions by supplying the Audience specific keys to the contact at time of creation or updating.\nYou may mark permissions as granted or denied. Simply setting these permissions will not make your audience GDPR compliant.\nSee the [Mailchimp GDPR Tutorial](https://mailchimp.com/help/collect-consent-with-gdpr-forms/) for a more complete description of Marketing Permissions and how to use them.\n\n```kotlin\n    val emailPermissionKey = \"1234567890\" // Example Key\n    val mailPermissionKey = \"2345678901\" // Example Key\n    val advertisingPermissionKey = \"3456789012\"\n    val newContact = Contact.Builder(\"example@email.com\")\n           .setMarketingPermission(emailPermissionKey, true)\n           .setMarketingPermission(mailPermissionKey, true)\n           .setMarketingPermission(advertisingPermissionKey, true)\n           .build()\n    val sdk = Mailchimp.sharedInstance()\n    sdk.createOrUpdateContact(newContact)\n```\n\n#### Retrieving Marketing Permission Keys\n\nSee the [Mailchimp SDK documentation](https://mailchimp.com/developer/guides/mobile-sdk-android-use/#Marketing_Permissions) for details on setting up marketing permissions.\n\n## Collecting contact events\n\n### Adding an event\n\nTo add an event associated with a contact, pass the email, event name, and properties (optional) into the `addContactEvent` method. This will add the event to the specified contact.\nUnlike adding or updating contact information, event requests will excecute immediately and will not be reattempted if they fail.\n\n```kotlin\n    val mailchimpSdk = Mailchimp.sharedInstance()\n    val eventProperties = mapOf(\"item_id\" to \"12894309543\")\n    mailchimpSdk.addContactEvent(\"example@email.com\", \"User Browsed Item\", eventProperties)\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.\nProperties are passed into the request as a Map\u003cString, String\u003e, the former being the name and the latter being the value.\n\n## Demo App\n\n### Autofilling Demo SDK Key (Optional)\n\nOn a Unix-like OS, in your home (~) folder, go into the .gradle folder and open or create a gradle.properties file.\nAdd the following key-value pair to have your SDK Key for the demo app filled in automatically.\n\n```\nMAILCHIMP_SDK_DEMO_KEY=\u003cYOUR_SDK_KEY\u003e\n```\n\nReplacing `\u003cYOUR_SDK_KEY\u003e` with the SDK Key you wish to use.\n\n## FAQ\n\nDo you have an iOS version?\n\u003eYes! You can find it [here](https://github.com/mailchimp/Mailchimp-SDK-iOS)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailchimp%2Fmailchimp-sdk-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmailchimp%2Fmailchimp-sdk-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailchimp%2Fmailchimp-sdk-android/lists"}