S2S Integration

Server-to-Server Integration (S2S)

This API allows you to send us custom events through your server, that occur inside or outside of your application but are not sent by the SDK. To send custom events from your server, use the following API:

Method: POST

URL: "https://analytics.metrix.ir/inappevent/{appId}"

appId: appId is the unique key for your app. This key can be found through your application setting in Metrix Dashboard.

Path Variable

{
  "appId": "APP_ID"
}

In order to find your dev-key which is generated uniquely for each application, go to the settings page of your application and look for the S2S Integration sub-menu. Copy the dev-key from this page. Also, to ensure the security, please add the public ip address of your servers to the Ip Address field. This will make sure that requests sent from these servers will be considered by Metrix servers.

Request Header

{
	"Authorization":  "DEV_KEY"
}

Request Body

{
  "metrixUserId": "METRIX_USER_ID",
  "metrixSessionId": "METRIX_SESSION_ID",

  "idfa": "IDFA",   // for ios
  "advertisingId": "GOOGLE_PLAY_SERVICES_ADVERTISING_ID",   // for Android

  // A JSON containing a rich in-app event attributes - must be String to String
  "customAttributes": {
    "content_type": "wallets",
    "content_id": "hrhfwbrfybwa"
  },

  // A JSON containing a rich in-app event metrics - must be String to Double
  "customMetrics": {
    "value": 130.5
  },

  "deviceIp": "USER_DEVICE_IP",
  "eventSlug": "EVENT_SLUG",              // e.g. "taqsq"
  "eventTime": "EVENT_TIMESTAMP_MILLIS"   // e.g 1570274953412 timestamp in millisecond
}

Revenue Event

You should provide following parameters for revenue events:

{
  "customAttributes": {
    // IRR, USD, EUR
    "_currency": "IRR"
  },
  "customMetrics": {
    "_revenue": 53.700
  }
}

Parameters

All the parameters inside the URL and Header are required and should be provided in every API call.

Required parameters

metrixUserId: The id that Metrix generates for each user. For more information, see our documentation
advertisingId or idfa or oaid: As you know, idfa is used for iOS devices and advertisingId is used for Android devices (and oaid is used by Huawei devices). Send S2S custom events based on the device type (iOS or Android) that the events are fired from. Filling none or both of them will cause a 400 bad request error.
eventSlug: This is the same slug that is generated in Metrix dashboard while you define an event.
eventTime: The time when the event occurred inside the application. If this field is not set, Metrix will set this time with the received time of the event by its servers.

Optional Parameters

customAttributes: Use this field to send custom information. Use a JSON format for your data, and all the values should be String values.
customMetrics: Use this field to send custom information. Use a JSON format for your data, and all the values should be Double values.
deviceIp: You can send the device ip address by this field.
metrixSessionId: The id that Metrix generates for each user's session of your application. For more information, see our documentation

Errors received from Metrix server

Error Type	Error Code	Description
IDFA_AND_ADVERTISING_ID_SHOULD_NOT_BE_NULL	BAD_REQUEST: 400	As mentioned above, `advertisingId` or `idfa` parameters can not be empty and one of them must be provided based on the operating system.
ONLY_ONE_OF_IDFA_AND_ADVERTISING_ID_SHOULD_BE_SET	BAD_REQUEST: 400	As mentioned above, the `advertisingId` or `idfa` parameters can not be sent at the same time and only one of them must be sent.
S2S_FEATURE_NOT_AVAILABLE	FORBIDDEN: 403	You will receive this error if you have not enabled the S2S service in your pricing plan or application settings.
INVALID_PARAMETERS	FORBIDDEN: 403	If one of the submitted parameters is not correct, you will encounter this error. For example, send `dev-key` with a different value than what you entered in your application.
INVALID_PARAMETERS	FORBIDDEN: 403	If one of the submitted parameters is not correct, you will encounter this error. For example, the IP address of the server from which the request is sent is not among the IPs that you define in the dashboard settings.
EVENT_TYPE_DOES_NOT_EXIST	NOT_FOUND: 404	If the `slug` sent by you is not correct, you will receive this error.

Frequently Asked Questions about S2S integration

What is meant by S2S integration?

When your server as an advertiser is integrated with your chosen tracker server, it can send your application events data without the need of code, we are talking about s2s integration. This type of integration is used when your server infrastructure has key information such as transactions that you want to send to your tracker without the need for an SDK.

Why is S2S Integration important?

This integration approach is useful when it is not possible to edit the application source code for the attribution platform. But in general, you can use this feature in the following three cases:

Your team is not able to edit the source code of your application. For example, has left it to a third party.
Third party SDKs do not comply with your company policies as an advertiser.
You want to start monitoring your campaigns before updating your application

How can I integrate my server with a Metrix server?

To do this integration, go to the settings section of your application in the dashboard. You will need to enter your development key and your allowed IP address. for more guidance get help from the Metrix documentation.

Do certain applications need to use this integration feature?

This feature is suitable for all applications running in all areas. But applications which out-of-app payments are more common (such as banking, financial and electronic payment apps) can make more use of this service. However, other applications, such as shipping, which redirect the user to the payment gateway to pay for the trip, should take advantage of this integration.