| **Note:** The Memory Advice API Beta is now over and the library is deprecated.[learn more about alternative memory management approaches](https://developer.android.com/games/optimize/memory-allocation).

This guide describes how to integrate the[Jetpack release](https://developer.android.com/jetpack/androidx/releases/games)of the[Memory Advice API](https://developer.android.com/games/sdk/memory-advice/overview)in your app using Android Studio.

Games should use the Memory Advice API release that is recommended for their build environment. For Android Studio, we recommend the Jetpack release. For information about releases for other build environments, such as the[Android Game Development Extension](https://developer.android.com/games/agde)(AGDE), see[Distributions](https://developer.android.com/games/sdk/memory-advice/overview#distributions).

## Add the library

This section describes how to add the library to your Android Studio (Android Gradle Plugin) project.

### Add the dependencies

To add the library to your Android Studio project, complete the following steps:

1. Enable Android Jetpack library in the project level[`gradle.properties`](https://developer.android.com/studio/build#properties-files)), the file normally is located in root directory of your project:

         android.useAndroidX=true

2. Open the module level`build.gradle`file and add the following`implementation`to the dependencies block. This declares[the memory advice API dependencies](https://developer.android.com/jetpack/androidx/releases/games)in your app.

        dependencies {
            implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
        }

3. Specify the NDK version inside the`android`block:

        ndkVersion "23.1.7779620"

   Make sure to choose a version of the NDK compatible with Memory Advice API. A list of supported NDK versions is available on the[Android Games Jetpack Release page](https://developer.android.com/jetpack/androidx/releases/games).
4. Declare additional build flags for CMake. To do so, add the following code to the`defaultConfig`block that is inside the`android`block:

        externalNativeBuild {
            cmake {
                cppFlags '-std=c++14'
                // c++_shared flavor is the only supported STL type.
                arguments "-DANDROID_STL=c++_shared"
            }
        }

5. Enable the[Prefab](https://developer.android.com/studio/build/dependencies#native-dependencies-aars)feature. For Android Gradle Plugin(AGP) 4.1 or higher, add the following code to the`android`block:

        buildFeatures {
           prefab true
        }

   If you are using AGP 4.0 or older, see the[Prefab page](https://developer.android.com/studio/build/dependencies#native-dependencies-aars)for configuration instructions.
6. Save the file. If you see the following message, click the**Sync Now**button to update your project:

         Gradle files have changed since last project sync. A project sync may be
         necessary for the IDE to work properly.

### Configure CMake for C/C++ build

To add the header files and runtime library for Memory Advice API into your project, open your project's main`CMakeLists.txt`file. In the**Project** pane, the file is in**app \> src \> main \> cpp**. After opening the file, perform the following steps:

1. Near the top of the file, add the following line after any`cmake_minimum_required`and`project`lines:

        find_package(games-memory-advice REQUIRED CONFIG)

2. In the`target_link_libraries`command, add`games-memory-advice::memory_advice`. This makes the Memory Advice API a dependency to your project's native library and includes it in your final application package. The update should look similar to the following:

        target_link_libraries(
            your-native-lib

            #link memory advice to the project
            games-memory-advice::memory_advice

            #rest of the dependencies
            #...
        )

### Configure the Java files

The native library included with the Memory Advice API is`libmemory_advice.so`. It is a compiling dependency for your app's own C/C++ shared library, and is automatically loaded when your app loads its own shared library with the`System.loadlibrary()`function.

This step is optional.

1. Find the java code in your project that loads the native libraries. If it doesn't exist, add it. The code should look similar to`System.loadLibrary("your-native-lib")`, and is located in a`static`block.

2. Add`System.loadLibrary("memory_advice")`under`System.loadLibrary("your-native-lib")`. The update should look similar to the following:

        static {
            System.loadLibrary("your-native-lib");
            // Note: loading libmemory_advice.so is optional.
            System.loadLibrary("memory_advice");
        }

## Use the library

This section describes how to use the library.

### Add the header files

Include the following library header file in your project:  

        #include <memory_advice/memory_advice.h>

### Initialize the library

You need to initialize the library once when the app starts. To do so, add this code to your project:  

        MemoryAdvice_init(env, activity);

The`env`and`activity`parameters are the`JNIEnv*`and`jobject`variables that should be available to your native library. Every JNI call to your native library should contain these variables. If you are using the[GameActivity library](https://developer.android.com/games/agdk/game-activity), make sure to[attach the calling thread to the JavaVM](https://developer.android.com/training/articles/perf-jni#threads)before calling the`MemoryAdvice_init`function.

### Poll for memory state

You can retrieve the memory state of your app by polling the library at the interval of your choosing. Use the[MemoryAdvice_getMemoryState](https://developer.android.com/reference/games/memory-advice/group/memory-advice#memoryadvice_getmemorystate)function whenever you need to poll the library:  

        MemoryAdvice_MemoryState state = MemoryAdvice_getMemoryState();
        switch (state) {
          case MEMORYADVICE_STATE_OK:
            // The application can safely allocate significant memory.
            break;
          case MEMORYADVICE_STATE_APPROACHING_LIMIT:
            //The application should minimize memory allocation.
            break;
          case MEMORYADVICE_STATE_CRITICAL:
            // The application should free memory as soon as possible,
            // until the memory state changes.
            break;
        }

### Set up a watcher

You can also set up[a watcher](https://developer.android.com/reference/games/memory-advice/group/memory-advice#memoryadvice_registerwatcher)and register the Memory Advice API, and your watcher function will get called when the state is either approaching the limit or the critical[memory state](https://developer.android.com/reference/games/memory-advice/group/memory-advice#memoryadvice_memorystate)(but not for the ok state). For example, the following code creates a watcher and requests a Memory Advice API notification every 2 seconds:  

        static int USER_DATA;
        constexpr int callback_waittime_ms = 2000;

        void callback(MemoryAdvice_MemoryState state, void* context) {
            switch (state) {
              case MEMORYADVICE_STATE_APPROACHING_LIMIT:
                //The application should minimize memory allocation.
                break;
              case MEMORYADVICE_STATE_CRITICAL:
                // The application should free memory as soon as possible,
                // until the memory state changes.
                break;
            }
        }

        MemoryAdvice_registerWatcher(callback_waittime_ms, callback, &USER_DATA);

## What's next

See the[overview](https://developer.android.com/games/sdk/memory-advice/overview)for[additional resources](https://developer.android.com/games/sdk/memory-advice/overview#additional_resources)and[reporting issues](https://developer.android.com/games/sdk/memory-advice/overview#issues_and_feedback).