{"id":30312731,"url":"https://github.com/mparticle/mparticle-unity-plugin","last_synced_at":"2025-10-04T01:41:09.846Z","repository":{"id":17518769,"uuid":"20306748","full_name":"mParticle/mparticle-unity-plugin","owner":"mParticle","description":"Unity plugin for the mParticle platform","archived":false,"fork":false,"pushed_at":"2025-08-11T15:04:23.000Z","size":83931,"stargazers_count":3,"open_issues_count":4,"forks_count":5,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-08-17T17:19:58.021Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mParticle.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2014-05-29T20:03:16.000Z","updated_at":"2022-03-30T18:47:10.000Z","dependencies_parsed_at":"2023-02-10T04:16:02.355Z","dependency_job_id":"3805ccac-2a70-42df-8468-8205662d814d","html_url":"https://github.com/mParticle/mparticle-unity-plugin","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/mParticle/mparticle-unity-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mParticle%2Fmparticle-unity-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mParticle%2Fmparticle-unity-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mParticle%2Fmparticle-unity-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mParticle%2Fmparticle-unity-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mParticle","download_url":"https://codeload.github.com/mParticle/mparticle-unity-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mParticle%2Fmparticle-unity-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278254470,"owners_count":25956598,"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","status":"online","status_checked_at":"2025-10-03T02:00:06.070Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-08-17T17:14:25.061Z","updated_at":"2025-10-04T01:41:09.820Z","avatar_url":"https://github.com/mParticle.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://static.mparticle.com/sdk/mp_logo_black.svg\" width=\"280\"\u003e\n\n## Unity Plugin\n\nThis is the mParticle Unity plugin - use it to send your data to the [mParticle platform](https://www.mparticle.com/) and off to 100+ app services. The plugin exposes a native C# interface for direct use from Unity scripts, and is bundled with mParticle's native SDKs for iOS and Android. With the mParticle Unity SDK, developers can leverage mParticle's wide range of supported integrations that are otherwise unsupported by Unity.\n\n## Plugin Setup\n\nDownload and import the plugin package to get started:\n\n1.  Navigate to the [releases page](https://github.com/mParticle/mparticle-unity-plugin/releases), download `mParticle.unitypackage`\n2.  Open an existing Unity project or create a new project\n3.  Open the package directly, or import it to your project by selecting Assets -\u003e Import Package -\u003e Custom Package...  \n\n### iOS Setup\n\n`mParticle.unitypackage` contains the mParticle Apple SDK as a dynamic framework library and the required headers which will be automatically imported into your project.\n\nYou may need to add the mParticle Apple SDK as an embedded library in your xcode project build settings (under General -\u003e Embedded Binaries). You may also need to build the \"Device SDK\" project from Unity (under Player Settings -\u003e Target Device) first and then switch to \"Simulator SDK\" if you wish to run on the simulator.\n\n\u003e Warning: the binary artifact for iOS contains simulator architectures (x86_64 and i386). These are provided to allow you to test on the simulator but must be stripped prior to submitting to the App Store or your app may be rejected. See this radar for more information: http://www.openradar.me/radar?id=6409498411401216\n\n#### Automated Xcode configuration\n\n`mParticle.unitypackage` includes `PostprocessBuildPlayer_mParticle` that automates several Xcode project configuration steps that are required to successfully build your application for the iOS platform. During the build process, Unity will locate and execute this script.\n\n\u003e Starting with Unity 5.3, post-process scripts are not run automatically. In those cases, the script will be run by `mParticleBuildPostprocessor.cs` instead.\n\nEnsure your Xcode project is in a folder called `iOS` and that the folder is in the root of your unity project folder.\n\n#### Manual Xcode configuration\n\nYou can also configure Xcode manually by adding the required frameworks specified in the [Apple SDK's manual installation guide](https://github.com/mParticle/mparticle-apple-sdk/wiki/Manual-installation-instructions#manual-installation).\n\n### Android Setup\n\n`mParticle.unitypackage` contains the mParticle core AAR artifact which will be automatically imported into your project.\n\n## Usage\n\n### mParticle Singleton\n\nThe mParticle Unity package contains a class file named `MParticle.cs`, which is a Unity `Monobehavior` that exposes the mParticle API via `MParticle.Instance`.  The package also contains the classes `MParticleiOS` and `MParticleAndroid`. These classes are used by the mParticle singleton to interact with the native iOS and Android libraries. You should never access those classes directly from your code.\n\n### Initialization\n\nThe plugin must be initialized with your mParticle workspace key and secret prior to use, for example by placing the following into you main script's `Awake` method:\n\n```cs\nusing UnityEngine;\nusing mParticle;\nnamespace MyProject\n{\n    public class Example : MonoBehaviour\n    {\n        void Awake ()\n        {\n         //use the correct workspace API key and secret for iOS and Android\n         #if UNITY_ANDROID\n          \t\tapiKey = \"REPLACE ME ANDROID KEY\";\n\t\t\t\tapiSecret = \"REPLACE ME ANDROID SECRET\";\n         #elif UNITY_IPHONE\n          \t\tapiKey = \"REPLACE ME IOS KEY\";\n\t\t\t\tapiSecret = \"REPLACE ME IOS SECRET\";   \n         #endif\n        }\n        \n        new MParticle().Initialize(new MParticleOptions()\n        {\n        \tApiKey = apiKey,\n        \tApiSecret = apiSecret\n        });\n    }\n}\n```\n\n#### MParticleOptions\n\nIt is now required to initialize the SDK with an MParticleOptions object. MParticleOptions' only required fields are ApiKey and ApiSecret:\n\n```cs\n\tMParticle.Instance.Initialize (new MParticleOptions () {\n\t\t\tApiKey = key,\n\t\t\tApiSecret = secret,\n\t\t\tInstallType = InstallType.KnownUpgrade,\n\t\t\tEnvironment = mParticle.Environment.Development,\n\t\t\tDevicePerformanceMetricsDisabled = false,\n\t\t\tIdDisabled = false,\n\t\t\tUploadInterval = 650,\n\t\t\tSessionTimeout = 50,\n\t\t\tUnCaughtExceptionLogging = false,\n\t\t\tLogLevel = LogLevel.VERBOSE,\n\t\t\tLocationTracking = new LocationTracking (\"GPS\", 100, 350, 22),\n\t\t\tPushRegistration = new PushRegistration () {\n\t\t\t\tAndroidSenderId = \"12345-abcdefg\",\n\t\t\t\tAndroidInstanceId = \"andriod-secret-instance-id\",\n\t\t\t\tIOSToken = \"09876654321qwerty\"\n\t\t\t},\n\t\t});\n```\n\n##### Initial Identify Request \u0026 IdentityStateListeners\nThe identity API is an integral part of the mParticle platform. The SDK operates is such a way that requires a current `MParticleUser` to be present. It is explained more in the Android \u0026 iOS documentation, but the way we go about ensuring this is to make a call to the `IdentityApi.Identify()` endpoint upon initialization. By default, we use the user identities associated with the current, stored `MParticleUser`, or an empty request if an application is running for the first time. \n\nUsing `MParticleOptions`, you have an option to override this default behavior, by registering a custom `IdentityApiRequest`.\n\nAdditionally, you may set a global OnUserIdentified delegate in `MParticleOptions`, which will be the most effective way to listen for any current `MParticleUser` changes that may take place as a result of the initial Identify request:\n\n```cs\n\tnew MParticle().Initialize(new MParticleOptions()\n        {\n        \tApiKey = apiKey,\n        \tApiSecret = apiSecret,\n        \tIdentifyRequest = new IdentityApiRequest () {\n\t\t\t\tUserIdentities = new Dictionary\u003cUserIdentity, string\u003e () {\n\t\t\t\t\t{ UserIdentity.CustomerId, \"Customer ID 1\" }\n\t\t\t\t},\n\t\t\t\tUserAliasHandler = ((previousUser, newUser) =\u003e newUser.SetUserAttribute(\"key\", \"value\"))\n\t\t\t},\n\t\t\tIdentityStateListener = newUser =\u003e Console.WriteLine(\"New MParticleUser found, Mpid = \" + newUser.Mpid);\n        });\n        \n```\n\n\n### Events\n\nEvents are central to many of mParticle's integrations; analytics integrations typically require events, and you can create mParticle Audiences based on the recency and frequency of different events.\n\n#### App Events\n\nApp Events represent specific actions that a user has taken in your app. At minimum they require a name and a type, but can also be associated with a free-form dictionary of key/value pairs:\n\n```cs\nMParticle.Instance.LogEvent (new MPEvent(\"Hello world\", EventType.Navigation) {\n\t\tDuration = 1000,\n\t\tStartTime = 123456789,\n\t\tEndTime = 1234557789,\n    \tInfo = new Dictionary\u003cstring, string\u003e{{ \"foo\", \"bar\" }},\n    \tCustomFlags = new Dictionary\u003cstring, List\u003cstring\u003e\u003e {\n\t\t\t{ \"custom flag 1\", new List\u003cstring\u003e () { \"one\", \"two\", \"five\" } },\n\t\t\t{ \"custom flag 2\", new List\u003cstring\u003e () { } },\n\t\t\t{ \"custom flag 3\", new List\u003cstring\u003e () { \"singleVal\" } }\n\t\t}\n    }\n);\n```\n#### Commerce Events\n\nThe `CommerceEvent` is central to mParticle's eCommerce measurement. `CommerceEvents` can contain many data points but it's important to understand that there are 3 core variations:\n\n- Product-based: Used to measure datapoints associated with one or more products\n- Promotion-based: Used to measure datapoints associated with internal promotions or campaigns\n- Impression-based: Used to measure interactions with impressions of products and product-listings\n\nHere's an example of a Product-based purchase event:\n\n```cs\nProduct[] products = new Product[2];\nproducts[0] = new Product(\"foo name\", \"foo sku\", 42, 2) {\n\tBrand = \"foo brand\",\n\tCategory = \"foo category\",\n\tCouponCode = \"foo coupon\",\n\tCustomAttributes = new Dictionary\u003cstring, string\u003e() {\n\t\t{\n\t\t\t\"Key1\",\n\t\t\t\"Value1\"\n\t\t},\n\t\t{\n\t\t\t\"Key2\",\n\t\t\t\"Value2\"\n\t\t}\n}\n\nproducts[1] = new Product(\"foo name 2\", \"foo sku 2\", 100, 3) {\n\tBrand = \"foo brand 2\";\n\tCategory = \"foo category 2\";\n\tCouponCode = \"foo coupon 2\";\n}\n\t\nTransactionAttributes transactionAttributes = new TransactionAttributes(\"foo transaction id\") {\n\tRevenue = 180,\n\tShipping = 10,\n\tTax = 15,\n\tAffiliation = \"foo affiliation\",\n\tCouponCode = \"foo coupon code\"\n};\nCommerceEvent eCommEvent = new CommerceEvent (\n    ProductAction.Purchase, \n    products, \n    transactionAttributes\n) {\n\tScreenName = \"HomeScreen\",\n\tCurrency = \"USD\",\n\tCustomAttributes = new Dictionary\u003cstring, string\u003e() {\n\t\t{\"key1\", \"value1\"}\n\t}\n}\nMParticle.Instance.LogEvent(eCommEvent);       \n```\n#### Screen events\n\n```cs\nMParticle.Instance.LogScreen(\"Test screen\");\n```\n\n### Identity\n\nVersion 2 of the MParticle Unity SDK supports the full range of IDSync features. For more in depth information about MParticle's Identity features, checkout either the [Android docs](http://docs.mparticle.com/developers/sdk/android/identity/) or the [iOS docs](http://docs.mparticle.com/developers/sdk/ios/identity) on the topic\n\n\n#### Accessing IdentityApi\n\nTo get a reference to the `IdentityApi`:\n\n```cs\nvar identityApi = MParticle.Instance.Identity;\n```\n\n#### Updating Identities \n\n\nUser identities allow you to associate specific identifiers with the current user: \n\n```cs\nIdentityApiRequest request = new IdentityApiRequest(identityApi);\n\t\trequest.UserIdentities.Add(UserIdentity.CustomerId, \"customerId\");\n\t\trequest.UserIdentities.Remove(UserIdentity.Email);\nidentityApi.Modify(request);\n```\n\nor\n\n```cs\nidentityApi.Modify(new IdentityApiRequest() \n                {\n                    UserIdentities = new Dictionary\u003cUserIdentity, string\u003e()\n                    {\n                        { UserIdentity.CustomerId, \"\" }\n                    }\n                });\n```\n\nIn addition to this, the underlying iOS and Android SDKs will automatically collect device IDs.\n\n#### User Attributes\n\nUser attributes allow for free form description of a user for segmentation and analytics:\n\n```cs\nidentityApi.CurrentUser.SetUserAttribute(\"foo attribute\", \"bar value\");\n```\n\n```cs\nidentityApi.CurrentUser.SetUserTag(\"foo tag\");\n```\n\n```cs\nidentityApi.CurrentUser.RemoveUserAttribute(\"foo attribute\");\n```\n\n#### Identity Change Callbacks\n\nSince the identity API calls, `Identify()`, `Login()`, `Logout()`, and `Modify()` are asynchronous, you can register a callback for the results of the request:\n\n```cs\n identityApi.Logout()\n         .AddSuccessListener(success =\u003e Console.WriteLine(success.User.UserAttributes))\n         .AddFailureListener(failure =\u003e Console.WriteLine(\"HttpCode = \" + failure.HttpCode + \"/nErrors = \" + failure.Errors));\n```\n\nAdditionally, the identity API allows you to register a global `MParticleUser state change listener. Any time the currentUser value changes, the callback will be invoked:\n\n```cs\nOnUserIdentified onUserIdentified = newUser =\u003e Console.WriteLine(\"New MParticleUser found, Mpid = \" + newUser.Mpid);\nidentityApi.Identity.AddIdentityStateListener(onUserIdentified);\n```\n\nThese delegates are tracked by references, so it is wise to maintain a reference to the listener if you plan on later removing it:\n\n```cs\nidentityApi.RemoveIdentityStateListener(onUserIdentified);\n```\n\n#### User Aliasing\n\nWhen a new user is returned through an identity API request, you may want to transition the SDK and data from the previous user to the new user:\n\n```cs\nidentityApi.Login(new IdentityApiRequest()\n            {\n                UserAliasHandler = (previousUser, newUser) =\u003e \n                {\n                    // do some stuff, but for example:\n                    var persistentAttribute = \"persistent user attribute\";\n                    if (previousUser.UserAttributes.ContainsKey(persistentAttribute))\n                    {\n                        newUser.UserAttributes.Add(persistentAttribute, previousUser.UserAttributes.GetValueOrDefault(persistentAttribute));\n                    }\n                }\n            });\n```\n\n####Identity Error Handling\nThe SDK will not retry Identity requests automatically. Identity Requests will return an `IdentityHttpResponse` object containing information on the error. On rare occurances you may receive and retry throttling errors:\n\n```cs\nidentityApi.Login()\n\t.AddFailureListener(failure =\u003e {\n\t\t\tif (failure.HttpCode == IdentityApi.ThrottleError) {\n\t\t\t\t//retry request here\n\t\t\t}\n\t\t\tConsole.WriteLine(\"Http Code = \" + failure.HttpCode + \"/nErrors = \" + failure.Errors.Aggregate (\"\", (composit, nextError) =\u003e composit += nextError.Message + \", \"));\n\t\t});\n```\n\n### License\n\n[Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmparticle%2Fmparticle-unity-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmparticle%2Fmparticle-unity-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmparticle%2Fmparticle-unity-plugin/lists"}