Update to reference query parameter substitution

README.md

@@ -25,7 +25,7 @@ Secondly, add the dependency in your app's `build.gradle`:
 
 ```
 dependencies {
-	implementation 'com.github.approov:approov-service-retrofit:3.0.2'
+	implementation 'com.github.approov:approov-service-retrofit:3.0.3'
 }
 ```
 
@@ -69,6 +69,8 @@ The `<enter-your-config-string-here>` is a custom string that configures your Ap
 
 This initializes Approov when the app is first created. A companion object allows other parts of the app to access the singleton Approov instance. All calls to `ApproovService` and the SDK itself are thread safe.
 
+It is possible to pass an empty string to indicate that no initialization is required. Only do this if you are also using a different Approov quickstart in your app (which will use the same underlying Approov SDK) and this will have been initialized first.
+
 ## USING APPROOV SERVICE
 You can then modify your code that obtains a `RetrofitInstance` to make API calls as follows:
 

SECRET-PROTECTION.md

@@ -60,6 +60,14 @@ With this in place the Approov interceptor should replace the `<secret-placehold
 
 Since earlier released versions of the app may have already leaked the `<secret-value>`, you may wish to refresh the secret at some later point when any older version of the app is no longer in use. You can of course do this update over-the-air using Approov without any need to modify the app.
 
+If the secret value is provided as a parameter in a URL query string with the name `<secret-param>` then it is necessary to notify the `ApproovService` that the query parameter is subject to substitution. You do this by making the call once, after initialization:
+
+```kotlin
+YourApp.approovService.addSubstitutionQueryParam("<secret-param>");
+```
+
+With this in place the Approov interceptor should replace any query parameter `<secret-param>` with the value `<secret-placeholder>` with the `<secret-value>`, if the app passes attestation. For example, if you have a URL of the form `https://mydomain.com/endpoint?api-key=api-key-placeholder` then you should call `YourApp.approovService.addSubstitutionQueryParam("api-key")` to ensure that, for any `api-key` parameter, if there is a secure string with the name `api-key-placeholder` then the query parameter value will be replaced with the secure string value before making the API request.
+
 ## REGISTERING APPS
 In order for Approov to recognize the app as being valid it needs to be registered with the service. Change the directory to the top level of your app project and then register the app with Approov:
 
@@ -182,4 +190,4 @@ catch(e: ApproovException) {
 // app has passed the precheck
 ```
 
-> Note you should NEVER use this as the only form of protection in your app, this is simply to provide an early indication of failure to your users as a convenience. You must always also have secrets essential to the operation of your app, or access to backend API services, protected with Approov. This is because, although the test itself is heavily secured, it may be possible for an attacker to bypass its result or prevent it being called at all. When the app is dependent on the secrets protected, it is not possible for them to be obtained at all without passing the attestation.
+> Note you should NEVER use this as the only form of protection in your app, this is simply to provide an early indication of failure to your users as a convenience. You must always also have secrets essential to the operation of your app, or access to backend API services, protected with Approov. This is because, although the Approov attestation itself is heavily secured, it may be possible for an attacker to bypass its result or prevent it being called at all. When the app is dependent on the secrets protected, it is not possible for them to be obtained at all without passing the attestation.

SHAPES-EXAMPLE.md

@@ -51,7 +51,7 @@ The `approov-service-retrofit` dependency needs to be added as follows to the `a
 Note that in this case the dependency has been added with the tag `main-SNAPSHOT`. For your projects we recommend you add a dependency to a specific version.
 
 ```
-implementation 'com.github.approov:approov-service-retrofit:3.0.2'
+implementation 'com.github.approov:approov-service-retrofit:3.0.3'
 ```
 
 Make sure you do a Gradle sync (by selecting `Sync Now` in the banner at the top of the modified `.gradle` file) after making these changes.

TOKEN-PROTECTION.md

@@ -92,7 +92,7 @@ catch(e: ApproovException) {
 // app has passed the precheck
 ```
 
-> Note you should NEVER use this as the only form of protection in your app, this is simply to provide an early indication of failure to your users as a convenience. You must always also have APIs protected with Approov tokens that are essential to the operation of your app. This is because, although the test itself is heavily secured, it may be possible for an attacker to bypass its result or prevent it being called at all. When the app is dependent Approov protected APIs they can never be accessed without passing the attestation, since it is not possible for an attacker to create a validly signed Approov token.
+> Note you should NEVER use this as the only form of protection in your app, this is simply to provide an early indication of failure to your users as a convenience. You must always also have APIs protected with Approov tokens that are essential to the operation of your app. This is because, although the Approov attestation itself is heavily secured, it may be possible for an attacker to bypass its result or prevent it being called at all. When the app is dependent Approov protected APIs they can never be accessed without passing the attestation, since it is not possible for an attacker to create a validly signed Approov token.
 
 If you wish to provide more direct feedback with the [Rejection Reasons](https://approov.io/docs/latest/approov-usage-documentation/#rejection-reasons) feature use: