Module Registration

Registration

To process the module registration message, override the processRegistrationRequest method in your MessageProcessor. From this method you must return a ModuleRegistrationResponse describing what your lambda-function can do and what it requires to contact your service, such as an API key.

1. Creating your ModuleRegistrationResponse and Describing your Service

Users of the mParticle platform will see the result of your module registration within our website's user interface. You should set a human-readable title for your service (such as your company's name), as well as a short description of your company including a link to your company's website, and it should be less than 230 characters.

Override the processRegistrationRequest method in your MessageProcessor and add the following code, customized for your service:

ModuleRegistrationResponse response = new ModuleRegistrationResponse("My Company Name", "1.0");
response.setDescription("<a href=\"http://www.yourcompany.com\" target=\"_blank\">Company Name</a> A short marketing description of what your company does.\"");

2. Permissions

Device IDs and User IDs

All users and data in the mParticle platform are associated with a set of device IDs such as Apple IDFA, and a set of identities such as Email. Event data and audience data received by your lambda function will always be associated with a user, but your lambda function must register for permission to receive each ID.

If you mark a device id or user identity as required, only users and their associated data that contain at least 1 of these IDs will be sent to your lambda function.

Location and IP Address

All mParticle event data can also be associated with location information, and your Firehose integration requires special permissions to access it. Depending on the app and how it has instrumented the mParticle SDK, location information may originate from the device sensors or may be determine to varying degrees of accuracy using reverse IP lookup. If your service needs access to location, you must request access by setting allowAccessLocation to true on the Permissions object of your module registration response:

permissions.setAllowAccessLocation(true);

Data can be sent into the mParticle platform via one of our native or web SDKs, as well as our server-to-server APIs, and will have an associated IP address of the originating client. If your service needs access to the IP address, you must request access by setting allowAccessIpAddress to true on the Permissions object of your module registration response:

permissions.setAllowAccessIpAddress(true);

See the example below or the javadocs for more information on populating the Permissions object in your ModuleRegistrationResponse response.

3. Account Settings

Once we enable your Firehose integration, all mParticle customers will have access to enable it for their account, and your Lambda function must be able to correctly identify the customer to process and send the data to your platform. For example, if your service uses an API key for authentication:

1. Your Lambda function must include an account setting representing the API key (marking it as required and confidential) in the ModuleRegistrationResponse.
2. When customers configure your integration via mParticle, they will be required to enter the API key that you have issued them.
3. Once enabled, mParticle will send data to your Lambda function including the value of the API key associated with that customer.
4. Your Lambda function can then use that API key to make authenticated calls to your API or service.

Settings need to be registered individually for Event and Audience-based integrations. Each setting will appear in the mParticle UI (unless marked as not-visible), and must contain the following:

1. An ID - you will use this in step #4 above to extract the setting value.
2. A short, human-readable name.
3. A description of what the setting means in the context of your service. This is used as the tooltip in the mParticle platform.
4. The data type of the setting
5. Required flag - if true, mutual customers will be required to enter a value for this setting to configure the integration
6. Confidential flag - if true, the value entered will be masked in the mParticle UI once set

See the following code snippet, the full example below, or the Javadocs for more on the various types of settings and properties of settings.

List<Setting> eventSettings = new ArrayList<>();
Setting apiKey = new TextSetting("apiKey", "API Key")
    .setIsRequired(true)
    .setIsConfidential(true)
    .setDescription("Your API key issued by <insert company here>.");
eventSettings.add(apiKey);
eventProcessingRegistration.setAccountSettings(eventSettings);

List<Setting> audienceSettings = new ArrayList<>();
audienceSettings.add(apiKey);
audienceProcessingRegistration.setAccountSettings(audienceSettings);

4. Event Registration

If you're writing a lambda function that can handle event and analytics data, you'll specify that your service supports certain types of events in your ModuleRegistrationResponse. This means you will only receive data when those events occur. The possible event types are:

1. Application State Transition
2. Custom Event
3. Error
4. Privacy Setting Change
5. Product Action
6. Promotion Action
7. Impression
8. Push Message Receipt
9. Push Subscription
10. Screen View
11. Session Start
12. Session End
13. User Attribute Change
14. User Identity Change
15. Attribution

See here for brief descriptions of each event type.

5. Audience Registration

Registering for Audience will allow your lambda function to receive Audience Subscription and Membership messages. During registration your lambda functions needs to specify the settings required to map and send audience data from mParticle to your service:

• (required) user modifiable account settings that your integration requires, such as an API key
• (optional) user modifiable audience-specific settings such as an audience ID
• (optional) internal audience-specific settings. These should be marked as not visible, so that users of the mParticle console cannot modify them. You can modify the values of these settings in your response to Audience Membership messages.

See here for more info on AudienceProcessingRegistration

Sample Registration

Refer to the sample project or the simple example below, which shows how to subscribe for both Event Processing and Audience:

 @Override
    public ModuleRegistrationResponse processRegistrationRequest(ModuleRegistrationRequest request) {
        ModuleRegistrationResponse response = new ModuleRegistrationResponse("My Company Name", "1.0");
        response.setDescription("A short marketing description of what your company does with a <a href=\"http://www.yourcompany.com\" target=\"_blank\">link to your website</a>.");

        //Set the permissions - the device and user identities that this service can have access to
        Permissions permissions = new Permissions();
        permissions.setUserIdentities(
                Arrays.asList(
                        new UserIdentityPermission(UserIdentity.Type.EMAIL, Identity.Encoding.RAW),
                        new UserIdentityPermission(UserIdentity.Type.CUSTOMER, Identity.Encoding.RAW)
                )
        );
        response.setPermissions(permissions);

        //the extension needs to define the settings it needs in order to connect to its respective service(s).
        //you can using different settings for Event Processing vs. Audience Processing, but in this case
        //we'll just use the same object, specifying that only an API key is required for each.
        List<Setting> processorSettings = Arrays.asList(
               new TextSetting("apiKey", "API Key")
                  .setIsRequired(true)
                  .setIsConfidential(true)
                  .setDescription("Your API key issued by <insert company here>.");
        );

        //specify the supported event types. you should override the parent MessageProcessor methods
        //that correlate to each of these event types.
        List<Event.Type> supportedEventTypes = Arrays.asList(
                Event.Type.CUSTOM_EVENT,
                Event.Type.PUSH_SUBSCRIPTION,
                Event.Type.PUSH_MESSAGE_RECEIPT,
                Event.Type.USER_ATTRIBUTE_CHANGE,
                Event.Type.USER_IDENTITY_CHANGE);

        //this extension only supports event data coming from Android and iOS devices
        List<RuntimeEnvironment.Type> environments = Arrays.asList(
                RuntimeEnvironment.Type.ANDROID,
                RuntimeEnvironment.Type.IOS);

        //finally use all of the above to assemble the EventProcessingRegistration object and set it in the response
        EventProcessingRegistration eventProcessingRegistration = new EventProcessingRegistration()
                .setSupportedRuntimeEnvironments(environments)
                .setAccountSettings(processorSettings)
                .setSupportedEventTypes(supportedEventTypes);
        response.setEventProcessingRegistration(eventProcessingRegistration);

        //Segmentation/Audience registration and processing is treated separately from Event processing
        //Audience integrations are configured separately in the mParticle UI
        //Customers can configure a different set of account-level settings (such as API key here), and
        //Segment-level settings (Mailing List ID here).
        List<Setting> subscriptionSettings = new LinkedList<>();
        subscriptionSettings.add(new IntegerSetting(SETTING_MAILING_LIST_ID, "Mailing List ID"));
        Setting invisibleSetting = new IntegerSetting(SETTING_INTERNAL_LIST_ID, "Internal ID");
        invisibleSetting.setIsVisible(false);
        subscriptionSettings.add(invisibleSetting);

        AudienceProcessingRegistration audienceRegistration = new AudienceProcessingRegistration()
                .setAccountSettings(processorSettings)
                .setAudienceSubscriptionSettings(subscriptionSettings);
        response.setAudienceProcessingRegistration(audienceRegistration);
        return response;
    }

Verifying

Once you have completed the implementation of your registration, you must send the result to mParticle for verification. See the testing section of this wiki for more information.

Next Step

Continue on to Event Processing