--- title: "Mapp Engage" slug: "mapp-engage-data-object-php-library-s2s" description: "Send Engage attributes, custom web events and user matching data (incl. ISO country, language and time zone) with the Mapp Intelligence PHP Library." status: "update" updated: 2026-11-02T14:49:46Z published: 2026-11-02T14:49:46Z canonical: "docs.mapp.com/mapp-engage-data-object-php-library-s2s" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.mapp.com/llms.txt > Use this file to discover all available pages before exploring further. # Mapp Engage Mapp Engage can be connected to your tracking setup to send **user-specific data in real time**. This enables you to enrich customer profiles with behavioral or preference-based information and to trigger automated actions directly in Engage. Typical use cases include: - **Sending dynamic user attributes** to Mapp Engage – for example, preferences or behaviors such as *“Size Finder used”* – to improve segmentation and targeting. - **Triggering a Custom Web Event** when a user interacts with a specific feature (e.g., a virtual fitting room), which can start an automation workflow in Engage. > [!NOTE] > Note > > To use this functionality, User Matching with Mapp Engage must be enabled. > > Details on setup and supported methods can be found in the Engage User Matching section below. --- **Supported Methods** | **Method** | **Description** | **Data Type** | | --- | --- | --- | | **constructor** | Initializes the Engage data object. | – | | **setAttributes** | Sends user-specific data to Mapp Engage, which can be stored as *Custom Profile Attributes*. These attributes can be created and managed directly in Engage. | {[key: string]: string} | | **addAttributes** | Adds additional user attributes to be transmitted to Mapp Engage. Works like *setAttributes*, but allows appending values to an existing set. | {[key: string]: string} | | **setEventName** | Defines the name of the Engage *Custom Web Event* (e.g. *“Size Finder Used”*). This event can trigger automations in the Engage Whiteboard. | string | | **setEventId** | Alternative to *eventName*. Refers to the numeric Engage *Custom Web Event ID* as defined in Engage. Typically used in advanced setups. | number | #### Generated request parameters | **Method** | **Request parameter** | **Constant** | | --- | --- | --- | | **setAttributes** / **addAttributes** | `eaj` (all attributes as one JSON object) | `ENGAGE_ATTRIBUTES` | | **setEventName** | `ecwen` | `ENGAGE_EVENT_NAME` | | **setEventId** | `ecwei` | `ENGAGE_EVENT_ID` | **Methods** construct ```php /** * MappIntelligenceEngage constructor. */ $engageData = new MappIntelligenceEngage(); ``` setAttributes ```php /** * @param array $a Sends user-specific data to Mapp Engage, which can be stored as Custom Profile Attributes. * These attributes can be created and managed in Engage. * * @return $this */ $engageData->setAttributes($a); ``` Every scalar value is accepted: strings, integers, floats and booleans (sent as `"true"` / `"false"`). `null`, `""`, NaN and infinite numbers are dropped. `setAttributes(null)` removes all attributes. addAttributes ```php /** * @param array $a Sends user-specific data to Mapp Engage, which can be stored as Custom Profile Attributes. * These attributes can be created and managed in Engage. * * @return $this */ $engageData->addAttributes($a); ``` setEventName ```php /** * @param string $e Defines the name of the Engage Custom Web Event (e.g. "Size Finder Used"). This can trigger automations in the Whiteboard. * * @return $this */ $engageData->setEventName($e); ``` setEventId ```php /** * @param number $e Alternative to eventName. Refers to the Engage Custom Web Event ID as defined in Engage. Mostly used for advanced setups. * * @return $this */ $engageData->setEventId($e); ``` **Example** ```php $engageData = new MappIntelligenceEngage(); $engageData    ->setAttributes(array('engage.attribute.fittingToolUsed' => "true")) ->setEventName("Virtual Fitting Room Used") ->setEventId(12345); $mappIntelligence = MappIntelligence::getInstance(); $mappIntelligence->track((new MappIntelligenceDataMap())->engage($engageData)); ``` --- ## User Matching This feature extends the Mapp Engage integration by enabling direct user matching between Mapp Intelligence and Engage. It allows you to identify or register users in Engage by transmitting their email address and related contact attributes. Use this functionality only if the Mapp Engage integration is enabled — it cannot be used standalone. Typical use cases include: - Registering new contacts in Engage when users sign up or subscribe on your website. - Updating existing Engage contacts with information such as name, gender, or opt-in status. - Associating website activity in Intelligence with known Engage users for automation and segmentation. --- **Supported Methods** | **Method** | **Description** | **Where to analyze** | | --- | --- | --- | | **constructor** | Initializes a new registration object for user matching with Engage. | – | | **setEmail** | Email address used to identify the user in Mapp Engage. | Mapp Engage | | **setGroupId** | Provides the group ID for a new registration in Engage. | Mapp Engage | | **setMode** | Defines the registration type used in Engage. Determines how new contacts are added to a group: - c = **Confirmed Opt-in** – new contacts are added directly and receive a confirmation message. - d = **Double Opt-in** – new contacts receive an invitation email and must confirm their subscription before being added. - o = **Opt-in (default)** – new contacts are added to the group without notification. | Mapp Engage | | **setFirstName** | First name of the contact in Engage. | Mapp Engage | | **setLastName** | Last name of the contact in Engage. | Mapp Engage | | **setGender** | Gender of the contact (u: undisclosed, f: female, m: male). | Mapp Engage | | **setTitle** | Contact’s title (e.g., Mr., Ms.). | Mapp Engage | | **setIsoCode** | Country of the contact as a two-letter ISO 3166-1 country code (e.g. `DE`). | Mapp Engage | | **setIsoLanguage** | Language of the contact as a two-letter ISO 639-1 language code (e.g. `de`). | Mapp Engage | | **setTimezone** | Time zone of the contact as an IANA time zone name (e.g. `Europe/Berlin`). | Mapp Engage | | **setOptIn** | Indicates whether the user has given consent (true: consent, false: no consent). Only when set to true will data be sent to Engage. | Mapp Engage | #### Generated request parameters | **Method** | **Request parameter** | **Constant** | | --- | --- | --- | | **setEmail** | `er1` | `REGISTRATION_EMAIL` | | **setGroupId** | `er2` | `REGISTRATION_GROUP_ID` | | **setMode** | `er3` | `REGISTRATION_MODE` | | **setFirstName** | `er4` | `REGISTRATION_FIRST_NAME` | | **setLastName** | `er5` | `REGISTRATION_LAST_NAME` | | **setGender** | `er6` | `REGISTRATION_GENDER` | | **setTitle** | `er7` | `REGISTRATION_TITLE` | | **setIsoCode** | `er8` | `REGISTRATION_ISO_CODE` | | **setIsoLanguage** | `er9` | `REGISTRATION_ISO_LANGUAGE` | | **setTimezone** | `er10` | `REGISTRATION_TIMEZONE` | | **setOptIn** | None. Without `setOptIn(true)`, none of the `er` parameters is sent. | – | **Methods** construct ```php $registrationData = new MappIntelligenceRegistration(); ``` setEmail ```php /** * @param string $e The Email address used to identify the user in Mapp Engage. * * @return $this */ $registrationData->setEmail($e); ``` setGroupId ```php /** * @param string $g Provide the group ID in case of a new registration for the user in Mapp Engage. * * @return $this */ $registrationData->setGroupId($g); ``` setMode ```php /** * @param string $m Provide the registration method used to register for marketing activities. * * @return $this */ $registrationData->setMode($m); ``` setFirstName ```php /** * @param string $f First name of the user to be used in Mapp Engage. * * @return $this */ $registrationData->setFirstName($f); ``` setLastName ```php /** * @param string $l Last name of the user to be used in Mapp Engage. * * @return $this */ $registrationData->setLastName($l); ``` setGender ```php /** * @param string $g Gender of the user. * * @return $this */ $registrationData->setGender($g); ``` setTitle ```php /** * @param string $t The title of the user to be used in Mapp Engage. * * @return $this */ $registrationData->setTitle($t); ``` setOptIn ```php /** * @param bool $o Provide information that the user consented to use their data. * * @return $this */ $registrationData->setOptIn($o); ``` The registration data (email, group ID, mode, first name, last name, gender, title, ISO code, ISO language and time zone) is only sent with `setOptIn(true)`. Without the opt-in no registration parameter is sent. setIsoCode ```php /** * @param string $i Two-letter ISO 3166-1 country code of the user (e.g. "DE") to be used in Mapp Engage. * * @return $this */ $registrationData->setIsoCode($i); ``` setIsoLanguage ```php /** * @param string $i Two-letter ISO 639-1 language code of the user (e.g. "de") to be used in Mapp Engage. * * @return $this */ $registrationData->setIsoLanguage($i); ``` setTimezone ```php /** * @param string $t IANA time zone name of the user (e.g. "Europe/Berlin") to be used in Mapp Engage. * * @return $this */ $registrationData->setTimezone($t); ``` **Example** ```php $registrationData = new MappIntelligenceRegistration(); $registrationData    ->setEmail('john@doe.com')    ->setGroupId('abc123')    ->setMode('c')    ->setFirstName('John')    ->setLastName('Doe')    ->setGender('m')    ->setTitle('Professor')    ->setIsoCode('DE')    ->setIsoLanguage('de')    ->setTimezone('Europe/Berlin')    ->setOptIn(true); $mappIntelligence = MappIntelligence::getInstance(); $mappIntelligence->track((new MappIntelligenceDataMap())->registration($registrationData)); ```