SDK Signature library integration

Adjust’s SDK Signature library is designed to be a standalone plugin for the Adjust SDK. This means you don’t need to change any of your code or change how you use the Adjust SDK in your app. Once you install the plugin, all requests made by the Adjust SDK will continue to work as expected.

Before you begin

To integrate the Signature library into your Unity app, ensure the following:

• The Android API version in use is 21 or greater.
• The Adjust SDK version in use is 4.37.2 or greater. This requirement applies even when the Adjust SDK is used indirectly.
• If you use Proguard, you must use the exact same Proguard configuration for both the Signature library and the Adjust SDK.

Migrating from Signature v1 or v2 library

If you previously used Signature v1 or Signature v2, you first need to remove the previous version before integrating the Signature library. To do this:

• If you previously integrated Signature v1, remove any code that calls to signature functions in your project.
• If you previously integrated Signature v2, remove the Signature v2 library from your project.

Updating the Signature Library

To update the Adjust Signature library, replace the existing Signature library with a new version and rerun your tests. You don’t need to make any immediate changes to your app logic or settings in Adjust as long as your certificates are configured and haven’t been altered. Remember to deactivate your secret IDs if they meet the following criteria:

• They’re no longer contributing to your install reporting.
• You’ve fully released a new version of your app (across all app platforms and stores).

Integrate the signature library (SDK v4 only)

Follow these steps to integrate the Signature library in your Unity project.

1. Fetch the Signature library content from GitHub.
2. Place the Android archive (.aar) file in the Assets/Adjust/Android directory inside your Unity project.
3. Place the iOS static framework (.a) in the Assets/Adjust/iOS directory inside your Unity project.

That’s it! The Signature library is now integrated into your project. Follow the steps in the next section to configure your digital certificates.

Set up your certificates in the Adjust suite

Once you integrate the Signature library into your app, all requests sent by the Adjust SDK to Adjust are signed. The Adjust SDK will also transmit relevant information to Adjust’s servers, including the fingerprint of your signing certificate.

A certificate fingerprint is a cryptographic hash of the public information held within a certificate. It can be used to verify the authenticity of an app.

The Signature library can’t verify the authenticity of your certificate fingerprints. The fingerprints need to be added to an allowlist in the Adjust Suite in order for requests containing them to be accepted by Adjust as authentic. To do this, you need to retrieve the certificate fingerprints and send them to Adjust.

From a keystore

If you use your own keystore, or if Android Studio generated a keystore for you, you can retrieve the certificate fingerprint by following these steps:

1. Find the keystore file (.jks) you used to sign the release version of your app. The keystore must be the one you used to sign the release version sent to the Google Play Store. If the keystore is different, your SDK requests will be rejected.

2. Run the following command to list your keys. Replace the parts in angle brackets with your information.

   $ keytool -list -v -keystore <path/to/keystore.jks> -alias <your_key_alias>

   This command prompts you for your keystore password. This is the password you defined when you generated the keystore.

   The final output looks like this:

   Alias name: Key0
   Creation date: May 15, 2018
   Entry type: PrivateKeyEntry
   Certificate chain length: 1
   Certificate[1]:
   Owner: CN=[Adjust, GmbH.]
   Issuer: CN=[Adjust, GmbH.]
   Serial number: 642f1b62
   Valid from: Tue May 15 09:46:06 CEST 2018 until: Sat May 09
   09:46:06 CEST 2043
   Certificate fingerprints:
   MD5: E7:88:9F:8C:9D:F4:14:C1:CF:E8:4C:97:F3:F2:3A:E3
   SHA1:
   C4:BD:07:91:BC:09:F8:B6:15:CD:BC:A3:3F:BC:68:8B:C2:EF:4F:F5
   SHA256:
   55:FB:97:0F:46:0F:94:EC:07:EA:01:69:50:5A:20:3F:A0:91:60:A4:F
   1:33:58:EA:76:DC:54:9E:A7:6A:B9:1A
   Signature algorithm name: SHA256withRSA
   Subject Public Key Algorithm: 2048-bit RSA key
   Version: 3

3. Save the SHA-1 fingerprint to add to your allowlist in the Adjust Suite.

From Google Play Internal App Sharing

If you use Google Play Internal App Sharing, you need to send both your organization’s SHA-1 certificate fingerprint and your Internal test certificate fingerprint to Adjust for allowlisting.

To extract the fingerprints:

1. Navigate to the Google Play Console and log in.
2. Select your app.
3. Select Release Management —> App Releases —> Manage internal app sharing > App certificates.
4. Save the SHA-1 certificate fingerprint for both the Internal test certificate and your organization’s keystore to add to your allowlist in the Adjust Suite.

From Google Play App Signing

If you use Google Play App Signing, you need to send both your organization’s SHA-1 certificate fingerprint and your Internal test certificate fingerprint to Adjust for allowlisting.

To extract the fingerprints:

1. Navigate to the Google Play Console and log in.
2. Select your app.
3. Select Release Management > App Signing.
4. Save the SHA-1 certificate fingerprint for both the App signing certificate and Upload certificate to send to Adjust.

From Huawei AppGallery App Signing

If you use Huawei AppGallery App Signing, you need to send both your organization’s SHA-1 certificate fingerprint and your Internal test certificate fingerprint to Adjust for allowlisting.

To extract the fingerprints:

1. Navigate to the App Signing page in AppGallery Connect and download the App signing certificate (certificate.pem).

2. Once you’ve downloaded the certificate, run the following command to output the SHA-1 fingerprint of the certificate.

   $ openssl x509 -fingerprint -in certificate.pem -noout -SHA1

   The output looks like this:

   SHA1 Fingerprint=C4:BD:07:91:BC:09:F8:B6:15:CD:BC:A3:3F:BC:68:8B:C2:EF:4F:F5

3. Save the fingerprint to add to your allowlist in the Adjust Suite..

Add your digital certificate fingerprints to Adjust’s allowlist

Once you’ve obtained your certificate fingerprints, do the following to add them to your allowlist:

1. Select your app in AppView to open the app details screen.
2. Select the Protection tab.
3. Select the Edit button on the Suspicious installs section.
4. Under the Android fingerprinting section, select New fingerprint.
5. Paste the SHA-1 fingerprint into the text box that appears.
6. Select Add.

That’s it! Your fingerprint is now allowlisted for your app.

Test your app

You can verify you have integrated the Signature library into your app using the Adjust Testing Console.

To test your Signature library integration:

1. Fully delete your app from the test device to ensure the install information is sent.

2. Forget the device using the Testing Console to clear out all information relating to the device. You can also use the forget_device endpoint by passing your app token and the advertising ID you obtained from the Adjust Insights app (available on iOS and Android). You can use any of the following advertising IDs: adid, android_id, gps_adid, idfa, idfv, imei, oaid.

   The call looks like this:

   $ curl -X POST 'https://app.adjust.com/forget_device?app_token={yourAppToken}&id={adid}'

3. Once you’ve cleared the device from the Testing Console, install the app on your test device and launch it to send install information to Adjust.

4. Input the test device’s advertising ID into the Testing Console to fetch the install event information. Check the following:

   1. The SignatureVerificationResult field should show a value of Valid Signature
   2. The SignatureVersion field should show a value of 3

If these fields are present and contain the correct information, you have successfully integrated the Signature library. If the fields display any other values, review the integration steps again or contact support@adjust.com for further assistance.

That’s it! You’ve successfully integrated the Signature library into your app. Once two attribution windows have passed, you can enforce SDK signature validation to make sure that only signed requests are accepted by Adjust.

Troubleshooting

Unknown CPU Architecture in AdjustSigSdk.a

In Unity Editor 2018 and later, you may receive an error message containing Unknown CPU Architecture. This error message is shown when the Unity Editor tries to apply the iOS static framework (.a) to non-iOS platforms. To fix the issue, select the AdjustSigSdk.a file and deselect all platforms except iOS in the Import Settings menu.