Upgrading from DarkMatter 4.1 -> 4.2

The DarkMatter library no longer includes ad support baked in, the game will need to provide a custom AdSystemPlugin that will handle it’s ad networks see AdSystemAdapter for more details. If you’d like to continue using the old MoPub ad implementation from previous version of DarkMatter it has been broken off into the AdSystemPluginMoPub.

Important Ads were the main reason to have a backed in AndroidManifest.xml file. Now that they have been removed the package will no longer import a base template for you so you’ll need to update the AndroidManiest manually. Each section that requires manifest changes will list the changes required in it’s integration guild.

System That require custom android setup

Updgrade steps

  • step 1: Before upgrading you should delete the libraries/DarkMatter/Ads folder and all of it’s contents.
  • step 2: Import the darkmatter 4.2.0 Unity package.
  • step 3: Update any custom build properties as needed (ie: android manifest, mainTemplate.gradle, etc)
  • step 4: (Optional: Only if youd like to use Magmic MoPub ads) Import AdSystemPluginMoPub unity package and follow it’s integration guide
  • step 5: Review general integration notes bellow to make sure standard library setup is completed.

Upgrading from DarkMatter < 4.0.0

DarkMatter 4.x has significant changes to how the Libraries are distributed and structured. If you are updating from a version of DarkMatter less than 4.0.0, then the simplest way to update is to write down your SKU ID keys, delete the entire ‘Libraries’ folder from your Unity project, and follow this integration guide like you are setting up a new app.

How to Integrate DarkMatter into a Unity Project

Step 1: Import

Import the DarkMatter_4.x.x_Unity.unitypackage into your Unity project. If your project has In App Purchases and you wish to use the StoreFront subsystem, ensure that the Unity IAP Service is enabled and imported in your app. More info can be found here: https://docs.unity3d.com/Manual/UnityIAP.html If your project does not use the StoreFront subsystem, you can delete the Libraries/StoreFront folder.

Step 2: Configuration

Search for the ‘Hive’ scriptable object in your hierarchy or manually find it at Libraries/Nucleus/src/Dependency Queue/Hive. Hive is the name of the system that automatically initializes the subsystems in order of their dependencies. Hit the Find Nodes and Link button to set it up.

Figure 1: Hive

Search for the ‘DarkMatter’ scriptable object in your hierarchy or manually find it at Libraries/DarkMatter/src/Nodes. This object holds the SKU ID keys given to you by your Magmic representative that identify your game in our systems.

Figure 2: DarkMatter

At this point your app will be able to properly initialize DarkMatter. You can attach a listener to the onInitializationComplete event of Nucleus.Hive.HiveManager to be notified when initialization is complete.

Out of the box, DarkMatter will automatically:

  • Download the manifest for your game
  • Track basic session analytics
  • Uniquely identify the player on our servers for the User Support and Prism systems

Further documentation on using a particular subsystem can be found in the sidebar on the left.

Step 2.1: Configuration Android

Build Gradle: DarkMatter requires your project to use the gradle build process in Unity. In the Assets/Plugins/Android folder you should see a darkmatterTemplate.gradle file which is the standard gradle build script used when exporting darkmatter for the Android platform.

  • If you don’t already use gradle you can rename the file to mainTemplate.gradle and when exporting from the Build menu select “Build System: Gradle” to export.
  • If you do use gradle you’ll need to merge the darkmatterTemplate.gradle properties into your existing mainTemplate.gradle file.
  • A note that anything in the gradle script with surrounded in double starts (**) is a unity special character and gets replaced on export.

Troubleshooting

Unable to find HiveManger (‘Hive.asset’)

Please create an instance with Assets->Create->Managers->Hive

You may see this message immediately after the first Import. Unity is just loading the assets in such an order that the script that checks for the existence of the Hive asset is loaded before the Hive asset can be searched for in Unity’s Asset Database.

You can safely ignore this message and it should not appear again. If it does, it might mean that your Hive asset was accidentally removed and you can just re-create it using the described menu item. After you create it, you’ll need to hit the Find Nodes and Link button again.

Assets/Libraries/StoreFront/src/IAP.cs(2,19): error CS0234: The type or namespace name Purchasing' does not exist in the namespace UnityEngine’. Are you missing an assembly reference?

You’ll get this error message if your Unity project does not have the Unity IAP Service. See Step 1 for more info.

Assets/Libraries/StoreFront/src/IAP.cs(26,15): error CS0246: The type or namespace name `IStoreListener’ could not be found. Are you missing an assembly reference?

If you have already resolved the above Unity IAP error but still see this error, you may just have to restart Unity. The reason is that all the Unity Purchasing code is under a UNITY_PURCHASING preproc that Unity enables when you enable the Unity IAP service and Unity found itself in a state where you have the Unity.Purchasing namespace but not the preproc.

Could not create texture from Assets/Libraries/Ads/Editor/iOS/MoreFunAdAPI/res/{various ad network resources}: File could not be read

These files are resources for the native iOS Ad network SDKs and are typically inside a .framework or .bundle folder. You can safely ignore these errors as they will be accessed by the native iOS SDK at runtime. These errors do not prevent Unity from entering Play Mode.

Magmic.Libraries.DarkMatter.DarkMatterError: The gameService node in the manifest is missing or invalid. AND/OR Magmic.Libraries.DarkMatter.DarkMatterError: Failed to initialize the user service data model, check to make sure the ‘userService’ node is present in the manifest.

These errors do not prevent your game from initializing or running, but we highly recommend having these nodes configured in your game’s Manifest. Documentation and example json can be found here and here.

I can’t use both DarkMatter and Crashlytics libraries in the same app!

Please see the workaround here: https://docs.google.com/a/magmic.com/document/d/1VGRfSf3kyElNzOtGufpBfzvBgNs1q7ZMHxx6qW3qEgM/edit?usp=sharing